> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Workflow Guide

> Master the pullbasectl command-line tool for efficient Pullbase management.

While the [Web UI](/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](/reference/cli).

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

```bash theme={null}
docker compose exec central-server pullbasectl <command>
```

<Tip>
  **Alias Tip:** Add this to your shell profile to run `pb` instead of the long command:
  `alias pb='docker compose exec central-server pullbasectl'`
</Tip>

### 2. via Go

If you have Go installed and the repository cloned, you can run directly from source:

```bash theme={null}
go run ./server/cmd/pullbasectl <command>
```

### 3. Native Binary

For frequent usage on your host machine, build the binary:

```bash theme={null}
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.

<Steps>
  <Step title="Get the bootstrap secret">
    The server writes this secret to `/app/secrets/bootstrap.secret`.

    ```bash theme={null}
    docker compose exec central-server cat /app/secrets/bootstrap.secret
    # Output example: 8f3...b2a
    ```
  </Step>

  <Step title="Run the bootstrap command">
    Use the secret to create your admin account.

    ```bash theme={null}
    docker compose exec central-server pullbasectl auth bootstrap-admin \
      --server-url http://localhost:8080 \
      --bootstrap-secret "YOUR_SECRET_FROM_ABOVE" \
      --username admin \
      --password 'SecurePassword123!'
    ```
  </Step>
</Steps>

### 2. Login & Token Reuse

Instead of passing credentials with every command, login once and export the token.

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
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:

<Steps>
  <Step title="Register the server">
    ```bash theme={null}
    docker compose exec central-server pullbasectl servers create \
      --server-url http://localhost:8080 \
      --id "web-01" \
      --name "Web Server 01" \
      --environment-id 1
    ```
  </Step>

  <Step title="Create an agent token">
    ```bash theme={null}
    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_`.*
  </Step>

  <Step title="Generate install script (Optional)">
    You can generate a one-liner to run on the target server:

    ```bash theme={null}
    docker compose exec central-server pullbasectl servers install-script \
      --server-url http://localhost:8080 \
      --id "web-01" \
      --token "pbt_YOUR_TOKEN"
    ```
  </Step>
</Steps>

### Create/List/Delete Users

Manage access for your team.

```bash theme={null}
# 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"
```

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

### Validate Config Locally

Validate your `config.yaml` before pushing to Git to prevent errors.

```bash theme={null}
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.
  ```bash theme={null}
  --ca-cert /path/to/ca.crt
  ```
* **Development Only:** Skip verification (insecure).
  ```bash theme={null}
  --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.