New to the CLI? Check out the CLI Guide for workflows and examples. pullbasectl ships with the Pullbase Docker image and is available inside the container at /pullbasectl. You can run it from the host by invoking the container or by copying the binary out of the image.
# Run pullbasectl from the official image
alias pullbasectl='docker run --rm pullbaseio/pullbase:latest pullbasectl'
Global options
These options are available on most commands:
| Flag | Description |
|---|
--server-url | Pullbase server base URL (e.g., http://localhost:8080) |
--admin-token | Admin JWT token for authentication |
--username | Admin username (alternative to --admin-token) |
--password | Admin password (use with --username) |
--password-file | Path to file containing admin password |
--ca-cert | Path to CA certificate bundle for TLS verification |
--insecure-skip-verify | Skip TLS certificate verification (not recommended) |
Set the environment variable PULLBASE_ADMIN_TOKEN to avoid repeating --admin-token on every command:export PULLBASE_ADMIN_TOKEN=$(pullbasectl auth login ... | jq -r '.access_token')
Authentication commands
pullbasectl auth bootstrap-admin
Initializes the first admin using the one-time bootstrap secret.
pullbasectl auth bootstrap-admin \
--server-url http://localhost:8080 \
--bootstrap-secret-file /app/secrets/bootstrap.secret \
--username admin_user \
--password 'ChangeMeNow123!'
Admin bootstrap completed successfully.
Username: admin_user
Access token (store securely):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
pullbasectl auth login
Exchange a username and password for an admin JWT.
pullbasectl auth login \
--server-url http://localhost:8080 \
--username admin_user \
--password 'ChangeMeNow123!'
--admin-token.
Server commands
Manage servers (agents) registered with Pullbase.
pullbasectl servers list
List all servers, optionally filtered by environment.
pullbasectl servers list \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT
ID NAME ENVIRONMENT STATUS DRIFTED AUTO-RECONCILE
web-01 Production Web production Applied no yes
api-01 API Server production Applied no yes
staging-01 Staging Server staging Drifted yes no
pullbasectl servers list \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--environment-id 1
pullbasectl servers create
Register a new server.
pullbasectl servers create \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id web-02 \
--name "Production Web 2" \
--environment-id 1
Server created successfully.
ID: web-02
Name: Production Web 2
Environment: 1
Auto-Reconcile: false
pullbasectl servers get
Get detailed information about a specific server.
pullbasectl servers get \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id web-01
Server: web-01
Name: Production Web
Environment: production
Auto-Reconcile: true
Status: Applied
Commit: a1b2c3d
Drifted: no
Last Seen: 2025-01-15T12:30:00Z
Created: 2025-01-01T09:00:00Z
pullbasectl servers delete
Delete a server registration.
Non-interactive stdin (piped/CI) requires --force; otherwise deletion is blocked to prevent accidental removal.
pullbasectl servers delete \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id web-02 \
--force
Server 'web-02' deleted successfully.
pullbasectl servers install-script
Generate a one-liner install script for deploying the agent to a server.
pullbasectl servers install-script \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id web-01 \
--token pbt_9BFzQYxK...
pullbasectl servers install-script ... | ssh user@server 'sudo bash'
Environment commands
Manage environments (Git repositories) that Pullbase tracks.
pullbasectl environments list
List all environments.
pullbasectl environments list \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT
ID NAME REPO BRANCH STATUS AUTO-RECONCILE
1 production https://github.com/acme/infra-config main active yes
2 staging https://github.com/acme/infra-config staging active no
pullbasectl environments create
Create a new environment.
pullbasectl environments create \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--name production \
--repo-url https://github.com/acme/infra-config \
--branch main \
--deploy-path configs/production
Environment created successfully.
ID: 1
Name: production
Repository: https://github.com/acme/infra-config
Branch: main
Deploy Path: configs/production
Status: pending
Auto-Reconcile: false
pullbasectl environments get
Get detailed information about an environment.
pullbasectl environments get \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id 1
Environment: production (ID: 1)
Repository: https://github.com/acme/infra-config
Branch: main
Deploy Path: configs/production
Provider: github
Installation: 12345678
Status: active
Auto-Reconcile: true
Deployed: a1b2c3d4e5f6
Last Webhook: 2025-01-15T12:00:00Z
Created: 2025-01-01T09:00:00Z
Updated: 2025-01-15T12:00:00Z
pullbasectl environments delete
Delete an environment. This will affect all associated servers.
pullbasectl environments delete \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id 2 \
--force
Environment 2 deleted successfully.
pullbasectl environments rollback
Initiate a rollback to a previous commit.
pullbasectl environments rollback \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id 1 \
--commit a1b2c3d \
--reason "Reverting broken nginx config"
Rollback initiated successfully.
ID: 42
Environment: 1
From: f6e5d4c
To: a1b2c3d
Status: pending
Reason: Reverting broken nginx config
pullbasectl environments rollback-list
List rollback history for an environment.
pullbasectl environments rollback-list \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--id 1
ID FROM TO STATUS CREATED
42 f6e5d4c a1b2c3d completed 2025-01-15T12:30:00Z
38 b2c3d4e f6e5d4c completed 2025-01-10T09:15:00Z
Status commands
View fleet-wide or per-server status.
pullbasectl status
Display server status. Requires one of --server-id, --environment-id, or --all.
Single server status:
pullbasectl status \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--server-id web-01
pullbasectl status \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--environment-id 1
pullbasectl status \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--all
Fleet Status Summary
Total: 5 servers
Healthy: 4
Drifted: 1
Errors: 0
Unknown: 0
SERVER ENVIRONMENT STATUS DRIFTED COMMIT LAST SEEN
web-01 production Applied no a1b2c3d 2 minutes ago
web-02 production Applied no a1b2c3d 1 minute ago
api-01 production Applied no a1b2c3d 3 minutes ago
staging-01 staging Drifted yes b2c3d4e 5 minutes ago
dev-01 development Applied no c3d4e5f just now
pullbasectl status \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--all \
--watch \
--interval 10
Ctrl+C to stop.
Config validation
pullbasectl validate-config
Validate a config.yaml file before deploying to your Git repository.
This command performs local validation only and does not require a connection to the Pullbase server. You can use it in CI pipelines or pre-commit hooks without authentication.
pullbasectl validate-config --file ./config.yaml
pullbasectl validate-config --file ./broken-config.yaml
✗ Config has 2 error(s):
FIELD LINE MESSAGE
files[0].path 5 path is required
files[1].content 12 content cannot be empty when source is not specified
--output json for programmatic parsing:
pullbasectl validate-config --file ./config.yaml --output json
GitHub App commands
pullbasectl github-app bootstrap
Validates GitHub App credentials locally and, when combined with --server-url, registers an environment.
Key flags:
--app-id, --private-key, --installation-id, --repository-id, --app-slug--server-url, --admin-token (optional) to create the environment in Pullbase--environment-name, --repo-url, --branch, --deploy-path
pullbasectl github-app status
Retrieve the GitHub App status for an environment:
pullbasectl github-app status \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--environment-id 5
Agent token commands
pullbasectl tokens list
List agent tokens for a server.
pullbasectl tokens list \
--server-url http://localhost:8080 \
--server-id web-01 \
--admin-token $ADMIN_JWT
ID Description Created Expires Last Used Active
1 initial 2025-01-15T12:00:00Z - 2025-01-15T12:30:00Z true
pullbasectl tokens create
Create an agent token.
pullbasectl tokens create \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--server-id web-01 \
--description "blue-green deployment" \
--expires-in 30
Token created successfully. Store this value securely:
pbt_9BFzQYxK...
Installation instructions:
Configure AGENT_TOKEN with this value when deploying the agent.
pullbasectl tokens revoke
Deactivate a token by ID.
pullbasectl tokens revoke \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--server-id web-01 \
--token-id 17
User commands
pullbasectl users create
Create a new user.
pullbasectl users create \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--new-username ops_user \
--new-password 'VerySecurePass!2024' \
--role viewer
pullbasectl users list
Paginate through active users.
pullbasectl users list \
--server-url http://localhost:8080 \
--admin-token $ADMIN_JWT \
--role admin \
--limit 50
User deletion currently requires the web UI or the REST API (DELETE /api/v1/users/{userID}). CLI support is planned.
Bootstrap wizard (interactive)
pullbasectl bootstrap wizard guides you through first-run setup, including admin creation and GitHub App configuration. The wizard prompts for values interactively and saves them to the server via the API.
pullbasectl bootstrap wizard
