CLI Reference - Pullbase Documentation

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...

Exchange a username and password for an admin JWT.

pullbasectl auth login \
  --server-url http://localhost:8080 \
  --username admin_user \
  --password 'ChangeMeNow123!'

Use the returned token for subsequent CLI calls with --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

Filter by environment:

pullbasectl servers list \
  --server-url http://localhost:8080 \
  --admin-token $ADMIN_JWT \
  --environment-id 1

`pullbasectl servers create`

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...

The output is a shell script you can pipe directly to bash on the target server:

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

Environment status:

pullbasectl status \
  --server-url http://localhost:8080 \
  --admin-token $ADMIN_JWT \
  --environment-id 1

Fleet-wide status:

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

Watch mode (live refresh):

pullbasectl status \
  --server-url http://localhost:8080 \
  --admin-token $ADMIN_JWT \
  --all \
  --watch \
  --interval 10

This clears the screen and refreshes status every 10 seconds. Press 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

✓ Config is valid

If validation fails:

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

Use --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

Output format:

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

`pullbasectl users delete`

Delete a user account.

Deletion is blocked if you attempt to delete the last active admin or your own account. The --delete-acct-username flag serves as confirmation and must match the username associated with the user ID.

pullbasectl users delete \
  --server-url http://localhost:8080 \
  --admin-token $ADMIN_JWT \
  --user-id 7 \
  --delete-acct-username "SomeAccount123"

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

​Global options

​Authentication commands

​pullbasectl auth bootstrap-admin

​pullbasectl auth login

​Server commands

​pullbasectl servers list

​pullbasectl servers create

​pullbasectl servers get

​pullbasectl servers delete

​pullbasectl servers install-script

​Environment commands

​pullbasectl environments list

​pullbasectl environments create

​pullbasectl environments get

​pullbasectl environments delete

​pullbasectl environments rollback

​pullbasectl environments rollback-list

​Status commands

​pullbasectl status

​Config validation

​pullbasectl validate-config

​GitHub App commands

​pullbasectl github-app bootstrap

​pullbasectl github-app status

​Agent token commands

​pullbasectl tokens list

​pullbasectl tokens create

​pullbasectl tokens revoke

​User commands

​pullbasectl users create

​pullbasectl users list

​pullbasectl users delete

​Bootstrap wizard (interactive)

Global options

Authentication commands

`pullbasectl auth bootstrap-admin`

`pullbasectl auth login`

Server commands

`pullbasectl servers list`

`pullbasectl servers create`

`pullbasectl servers get`

`pullbasectl servers delete`

`pullbasectl servers install-script`

Environment commands

`pullbasectl environments list`

`pullbasectl environments create`

`pullbasectl environments get`

`pullbasectl environments delete`

`pullbasectl environments rollback`

`pullbasectl environments rollback-list`

Status commands

`pullbasectl status`

Config validation

`pullbasectl validate-config`

GitHub App commands

`pullbasectl github-app bootstrap`

`pullbasectl github-app status`

Agent token commands

`pullbasectl tokens list`

`pullbasectl tokens create`

`pullbasectl tokens revoke`

User commands

`pullbasectl users create`

`pullbasectl users list`

`pullbasectl users delete`

Bootstrap wizard (interactive)