CLI Reference

The pai command-line tool is the primary interface for managing agent workloads, models, providers, and secrets on the Pai platform.

Commands

`pai create`

Create a resource from a YAML file. For AgentWorkloads, a unique name is auto-generated unless --name is provided. For other resource types (ModelBinding, Provider), the name from the YAML is used by default.

pai create -f <file> [--name <name>]

Flag	Description
`-f, --file <file>`	Path to the YAML manifest (required)
`--name <name>`	Override the resource name from the manifest

Examples:

# Create an agent (auto-generates name like openclaw-a7x3k9)
pai create -f agent.yaml

# Create an agent with a specific name
pai create -f agent.yaml --name openclaw-prod

# Create a model binding
pai create -f bindings/claude-haiku.yaml

# Create a service binding
pai create -f bindings/github-pr-writer.yaml

`pai apply`

Create or update a resource from a YAML file. If the resource already exists, it is updated in place. Works with any Pai resource type (AgentWorkload, ModelBinding, Provider).

pai apply -f <file> [--name <name>]

Flag	Description
`-f, --file <file>`	Path to the YAML manifest (required)
`--name <name>`	Override the resource name from the manifest

Examples:

# Apply an agent spec (uses name from YAML)
pai apply -f agent.yaml

# Apply to a specific named agent (overrides YAML name)
pai apply -f agent.yaml --name openclaw-a7x3k9

# Apply a model binding
pai apply -f bindings/gemini-flash.yaml

# Apply a service binding
pai apply -f bindings/telegram.yaml

`pai delete`

Delete a Pai resource by type and name.

pai delete <type> <name>

Argument	Description
`type`	Resource type: `agent`, `model`, `service`, `secret`
`name`	Name of the resource to delete

Example:

pai delete agent my-agent
pai delete model gemini-flash
pai delete service github-writer
pai delete secret gemini-key

`pai list`

List all agent workloads in the current namespace.

pai list

Example output:

NAME           STATUS    MODELS                TOKENS/DAY   URL                            AGE
my-agent       Running   gemini-flash          12,450       https://a7x3k9.pairun.dev      2h
data-analyst   Running   claude-sonnet         3,200        https://b2m4p7.pairun.dev      1d
test-bot       Pending   gemini-flash          0            --                             10s

`pai status`

Show detailed status for a specific agent workload, or all workloads if no name is given.

pai status [name]

Argument	Description
`name`	(Optional) Name of the agent workload

Example:

pai status my-agent

Example output:

Name:        my-agent
Namespace:   pai-system
Status:      Running
URL:         https://a7x3k9.pairun.dev
Image:       ghcr.io/pai-platform/openclaw:latest

Models:
  - gemini-flash (gemini / gemini-2.0-flash) — 12,450 / 1,000,000 tokens today

Services:
  - github-writer (github / api.github.com) — 34 requests today

Conditions:
  Available    True    Deployment has minimum availability
  Progressing  True    ReplicaSet has successfully progressed

`pai logs`

Stream or tail logs from an agent workload.

pai logs <name> [--tail N]

Flag	Description
`--tail N`	Number of recent log lines to show (default: all)

Example:

pai logs my-agent
pai logs my-agent --tail 100

`pai exec`

Execute a command inside a running agent container, or open an interactive TTY shell.

pai exec [-it] <name> [-- <cmd>]

Flag	Description
`-it`	Allocate a TTY (default when no command is given)

Examples:

# Single command
pai exec my-agent -- ls /workspace

# Interactive shell
pai exec -it my-agent /bin/bash

# Interactive shell (shorthand — -it inferred when no command given)
pai exec my-agent

`pai add model`

pai add model <name> [flags]

Flag	Description
`--provider <provider>`	LLM provider: `anthropic`, `openai`, `gemini`, `openrouter`, `azure-openai`, `vllm`
`--api-key <secret>`	Name of the Kubernetes Secret containing the API key
`--max-tokens-day <n>`	Maximum tokens per day (daily budget cap)
`--max-tokens-request <n>`	Maximum tokens per single request

Example:

pai add model claude-sonnet \
  --provider anthropic \
  --api-key anthropic-key \
  --max-tokens-day 500000 \
  --max-tokens-request 16000

pai add model gemini-flash \
  --provider gemini \
  --api-key gemini-key \
  --max-tokens-day 1000000

`pai add secret`

Create a Kubernetes Secret for use with model or service bindings.

pai add secret <name> --from-literal KEY=VAL [--from-literal KEY2=VAL2 ...]

Flag	Description
`--from-literal KEY=VAL`	Set a key-value pair in the secret. Can be repeated.

Example:

# Single key
pai add secret gemini-key --from-literal api-key=AIzaSy...

# Multiple keys (e.g., AWS credentials)
pai add secret aws-creds \
  --from-literal access_key_id=AKIA... \
  --from-literal secret_access_key=wJalr...

`pai add provider`

Create a Provider to connect agents to external services.

pai add provider <name> --provider <provider> [flags]

Flag	Description
`--provider <provider>`	Service provider: `github`, `telegram`, `slack`, `aws`, `azure`, `gcp`, etc.
`--secret-token <secret>`	Name of the Secret containing credentials
`--repos <repos>`	Comma-separated list of repositories (GitHub provider)

Example:

pai add provider github-writer \
  --provider github \
  --secret-token github-pat \
  --repos "myorg/repo-a,myorg/repo-b"

pai add provider telegram-bot \
  --provider telegram \
  --secret-token telegram-token

`pai get`

List resources of a specific type.

pai get <type>

Type	Description
`agents`	List all AgentWorkload resources
`models`	List all ModelBinding resources
`providers`	List all Provider resources
`secrets`	List all Pai-managed secrets

Example:

pai get agents
pai get models
pai get providers
pai get secrets

Example output (pai get models):

NAME            PROVIDER    MODEL               MAX/DAY     AGE
gemini-flash    gemini      gemini-2.0-flash     1000000    2d
claude-sonnet   anthropic   claude-sonnet-4-6    500000     1d

`pai scaling`

Show the autoscaling status and metric targets for an agent. Displays the current and desired replica counts, the configured metrics, cooldown settings, and the time of the last scale action.

pai scaling <name> [--watch]

Flag	Description
`--watch, -w`	Continuously refresh every 5 seconds (Ctrl-C to stop)

Examples:

# Show current scaling status
pai scaling my-agent

# Live view (refreshes every 5s)
pai scaling my-agent --watch

Example output:

Agent:       my-agent
Autoscaling: enabled
Replicas:    3 current / 4 desired  [min: 1, max: 5]
Last scale:  2m ago
Metrics:
  tokenRate    target 500 tok/min per replica
  http         target 5 per replica
               https://jira.company.com/rest/api/2/search?jql=project%3DAI+AND+status%3DOpen  jsonPath: total
  poll interval: 30s  scale-up cooldown: 60s  scale-down cooldown: 300s

note

If autoscaling is not configured for the agent, the command reports it and explains how to add spec.autoscaling to the workload. When autoscaling is configured, pai scaling shows the status immediately — it does not wait for the first poll cycle (typically up to 30s after deployment).

`pai audit`

View or verify the tamper-evident HMAC-SHA256 audit chain for an agent. The audit chain covers every SERVICE_CALL, POLICY_DENY, EXEC, LLM_CALL, and TOOL_CALL event and is stored on a dedicated PVC in the sidecar — inaccessible from the agent container.

pai audit <name> [--verify] [--limit N] [--since 1h|24h] [--format json]

Flag	Description
`--verify`	Recompute the full HMAC chain and confirm integrity
`--limit N`	Number of recent entries to show (default: 50)
`--since 1h\|24h`	Show entries from the last N hours
`--format json`	Output raw JSONL instead of pretty-printed table

Examples:

# Show recent audit events
pai audit my-agent

# Verify chain integrity
pai audit my-agent --verify

# Last hour, JSON format
pai audit my-agent --since 1h --format json

Example output:

  #   TIMESTAMP              EVENT          DETAIL
 2026-03-24 14:23:45    EXEC           /usr/bin/python3 agent.py
 2026-03-24 14:23:46    SERVICE_CALL   github-writer  pulls:create  myorg/repo ✓
 2026-03-24 14:23:47    LLM_CALL       claude-sonnet-4-6  in=1204 out=340  231ms
 2026-03-24 14:23:48    TOOL_CALL      bash  {"command":"ls /tmp"}

`pai config set-env` / `unset-env` / `list-env`

Manage user environment variables that are automatically injected into every AgentWorkload pod you create. Values are stored on your PaiAccessToken in Kubernetes — they persist across machines and CLI reinstalls.

pai config set-env <KEY> <VALUE>
pai config unset-env <KEY>
pai config list-env

Example:

pai config set-env GIT_AUTHOR_NAME "Jane Smith"
pai config set-env GIT_AUTHOR_EMAIL "jane@example.com"

pai config list-env
# User env vars (injected into all new agent pods)
#   GIT_AUTHOR_EMAIL = jane@example.com
#   GIT_AUTHOR_NAME  = Jane Smith

pai config unset-env GIT_AUTHOR_EMAIL

`pai version`

Print the Pai CLI and platform versions.

pai version

Example output:

Client:    v0.4.0
Platform:  v0.4.0 (pai-system namespace)
Gateway:   v0.4.0
Controller: v0.4.0

Commands​

pai create​

pai apply​

pai delete​

pai list​

pai status​

pai logs​

pai exec​

pai add model​

pai add secret​

pai add provider​

pai get​

pai scaling​

pai audit​

pai config set-env / unset-env / list-env​

pai version​

Commands

`pai create`

`pai apply`

`pai delete`

`pai list`

`pai status`

`pai logs`

`pai exec`

`pai add model`

`pai add secret`

`pai add provider`

`pai get`

`pai scaling`

`pai audit`

`pai config set-env` / `unset-env` / `list-env`

`pai version`