CLI Workflow Guide

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.

1. via Docker (Recommended)

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.

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

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!'

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:

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

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

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/Delete 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

# Delete a user's account
docker compose exec central-server pullbasectl users delete \
  --server-url http://localhost:8080 \
  --user-id 7 \
  --delete-acct-username "SomeAccount123"

User deletion is blocked if you attempt to delete the last active admin or your own account.

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

Run auth login again to get a new token.
Update your PULLBASE_ADMIN_TOKEN variable.

Foundations

Setup

Operations

Examples

Running the CLI

1. via Docker (Recommended)

2. via Go

3. Native Binary

Authentication

1. Bootstrap First Admin

Common Workflows

Create an Environment

Register Server & Install Agent

Create/List/Delete Users

Validate Config Locally

Troubleshooting

Host vs. Container URLs

TLS Errors

401 Unauthorized

​Running the CLI

​1. via Docker (Recommended)

​2. via Go

​3. Native Binary

​Authentication

​1. Bootstrap First Admin

​2. Login & Token Reuse

​Common Workflows

​Create an Environment

​Register Server & Install Agent

​Create/List/Delete Users

​Validate Config Locally

​Troubleshooting

​Host vs. Container URLs

​TLS Errors

​401 Unauthorized

Running the CLI

1. via Docker (Recommended)

2. via Go

3. Native Binary

Authentication

1. Bootstrap First Admin

2. Login & Token Reuse

Common Workflows

Create an Environment

Register Server & Install Agent

Create/List/Delete Users

Validate Config Locally

Troubleshooting

Host vs. Container URLs

TLS Errors

401 Unauthorized