Skip to main content
While the Web UI is excellent for monitoring and visual exploration, the CLI (pullbasectl) is the preferred tool for:
  • Automation: Scripting repetitive tasks or CI/CD pipelines.
  • Initial Setup: Bootstrapping the first admin and setting up environments.
  • Power Users: Rapidly executing commands without navigating menus.
This guide focuses on practical, workflow-oriented usage. For a complete list of flags, see the CLI Reference.

​
Running the CLI

You can run pullbasectl in three ways depending on your environment. The easiest way to run the CLI is using the binary already inside your running central-server container. 
docker compose exec central-server pullbasectl <command>
Alias Tip: Add this to your shell profile to run pb instead of the long command: alias pb='docker compose exec central-server pullbasectl'

​
2. via Go

If you have Go installed and the repository cloned, you can run directly from source: 
go run ./server/cmd/pullbasectl <command>

​
3. Native Binary

For frequent usage on your host machine, build the binary: 
go build -o pullbasectl ./server/cmd/pullbasectl
# Move to a directory in your PATH, e.g., /usr/local/bin
sudo mv pullbasectl /usr/local/bin/

​
Authentication

​
1. Bootstrap First Admin

When you first install Pullbase, no users exist. You must “bootstrap” the first admin using a secret file generated by the server.
1

Get the bootstrap secret

The server writes this secret to /app/secrets/bootstrap.secret.
docker compose exec central-server cat /app/secrets/bootstrap.secret
# Output example: 8f3...b2a
2

Run the bootstrap command

Use the secret to create your admin account.
docker compose exec central-server pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret "YOUR_SECRET_FROM_ABOVE" \
  --username admin \
  --password 'SecurePassword123!'

​
2. Login & Token Reuse

Instead of passing credentials with every command, login once and export the token. 
# Login and capture the token
TOKEN=$(docker compose exec central-server pullbasectl auth login \
  --server-url http://localhost:8080 \
  --username admin \
  --password 'SecurePassword123!' | grep -oE 'ey[a-zA-Z0-9._-]+')

# Export for your session
export PULLBASE_ADMIN_TOKEN=$TOKEN
Now you can run commands without auth flags: 
docker compose exec central-server pullbasectl users list --server-url http://localhost:8080

​
Common Workflows

​
Create an Environment

Environments group servers and link them to a Git repository configuration. 
docker compose exec central-server pullbasectl environments create \
  --server-url http://localhost:8080 \
  --name "production" \
  --repo-url "https://github.com/your-org/infra-config" \
  --branch "main" \
  --deploy-path "envs/prod"

​
Register Server & Install Agent

The standard flow to add a new server:
1

Register the server

docker compose exec central-server pullbasectl servers create \
  --server-url http://localhost:8080 \
  --id "web-01" \
  --name "Web Server 01" \
  --environment-id 1
2

Create an agent token

docker compose exec central-server pullbasectl tokens create \
  --server-url http://localhost:8080 \
  --server-id "web-01" \
  --description "Initial token"
Save the token output starting with pbt_.
3

Generate install script (Optional)

You can generate a one-liner to run on the target server:
docker compose exec central-server pullbasectl servers install-script \
  --server-url http://localhost:8080 \
  --id "web-01" \
  --token "pbt_YOUR_TOKEN"

​
Create/List Users

Manage access for your team. 
# List all users
docker compose exec central-server pullbasectl users list \
  --server-url http://localhost:8080

# Create a read-only user
docker compose exec central-server pullbasectl users create \
  --server-url http://localhost:8080 \
  --new-username "auditor" \
  --new-password "AuditPass123!" \
  --role viewer

​
Validate Config Locally

Validate your config.yaml before pushing to Git to prevent errors. 
docker compose exec central-server pullbasectl validate-config \
  --file ./configs/prod/config.yaml

​
Troubleshooting

​
Host vs. Container URLs

  • From Host: Access the API via http://localhost:8080.
  • From Container: If running pullbasectl inside another container in the same network, use the service name: http://central-server:8080.

​
TLS Errors

If you are using self-signed certificates (default in development):
  • Production: Always trust the CA. 
    --ca-cert /path/to/ca.crt
  • Development Only: Skip verification (insecure). 
    --insecure-skip-verify

​
401 Unauthorized

If you receive a 401 error, your token has likely expired (default 24h).
  1. Run auth login again to get a new token.
  2. Update your PULLBASE_ADMIN_TOKEN variable.