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 login`

Connect to a Pai platform. Stores credentials in ~/.pai/config.json as a named context.

pai login <url> [--token <token>] [--context <name>]

Flag	Description
`--token <token>`	Bearer token (prompted interactively if omitted)
`--context <name>`	Override the auto-derived context name

Examples:

# Connect by hostname (HTTPS auto-prepended)
pai login pairun.dev --token <tok>

# Connect to a raw IP (HTTP)
pai login 10.0.0.5:8080 --token <tok>

# Connect with a custom context name
pai login pairun.dev --token <tok> --context prod

`pai logout`

Remove stored credentials for the active (or specified) context.

pai logout [--context <name>]

`pai context`

Manage named auth contexts.

pai context list
pai context use <name>
pai context delete <name>

Example:

pai context list
# prod@pairun  (active)
# dev@pairun

pai context use dev@pairun

`pai run`

Create and run a task agent (an ephemeral run of a Agent). Streams events to the terminal while the agent runs.

pai run <name> --agent <def> [--task "<prompt>"]

Flag	Description
`--agent <def>`	Agent to run (required)
`--task <prompt>`	Initial prompt — auto-starts the agent loop immediately

Examples:

# Run a task agent and stream its output
pai run fix-bug-42 \
  --agent openclaw \
  --task "Fix the null pointer in auth middleware"

# Start idle (interactive — send prompts via pai chat or the event API)
pai run my-session --agent data-analyst

note

pai run creates an Agent resource with spec.type: task. You can also create task agents from YAML with pai apply -f task-agent.yaml.

`pai create`

Create a resource — either from a YAML file or by type and flags.

# From YAML (all resource types)
pai create -f <file> [--name <name>]

# Typed creation
pai create skill           <name> --from-dir <dir> [-d <description>]
pai create model-provider  <name> --provider <p> --api-key <key> [flags]
pai create secret          <name> --from-literal KEY=VAL [...]
pai create provider        <name> --provider <type> [flags]

From YAML

Creates any resource type from a manifest. For Agent resources, a unique suffix is appended to the name unless --name is given; for all other types the name from the YAML is used as-is.

# 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 provider (preferred)
pai create -f providers/anthropic.yaml

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

`pai create skill`

Upload a local directory as a named skill bundle.

pai create skill <name> --from-dir <dir> [-d <description>]

pai create skill coding-guidelines --from-dir ./skills/coding -d "Team coding standards"

`pai create model-provider`

Register a ModelProvider — one per LLM API subscription. Every model offered by that provider becomes available to any agent that references it as <name>/<model-id>.

pai create model-provider <name> --provider <p> --api-key <key> [--max-tokens-day <n>]

Flag	Description
`--provider <p>`	LLM provider: `anthropic`, `openai`, `gemini`, `openrouter`
`--api-key <key>`	API key (prompted interactively if omitted)
`--max-tokens-day <n>`	Daily token budget cap across all agents using this provider

pai create model-provider anthropic \
  --provider anthropic \
  --api-key sk-ant-... \
  --max-tokens-day 5000000

pai create model-provider google \
  --provider gemini \
  --api-key $GEMINI_API_KEY

`pai create secret`

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

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

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

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

`pai create provider`

Create a Provider to connect agents to external services.

pai create provider <name> --provider <type> [--secret-token <secret>] [--repos org/repo,...]

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

pai create provider github-writer \
  --provider github \
  --repos "myorg/repo-a,myorg/repo-b"

pai create provider telegram-bot \
  --provider telegram

`pai apply`

Create or update a resource from a YAML file (or stdin). If the resource already exists, it is updated in place. Supports multi-document YAML (--- separator).

pai apply -f <file> [--name <name>]
pai apply -f -           # read from stdin

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

Examples:

pai apply -f agent.yaml
pai apply -f agent.yaml --name openclaw-a7x3k9
cat agent.yaml | pai apply -f -

`pai get`

List or describe resources. Pass a name to get details on a single resource.

pai get [<type>] [<name>] [flags]

Type	Description
`agents` (default)	All Agent resources — service, task, and template (no `spec.type`) modes
`sessions`	Alias for task agents (`spec.type: task`) only
`model-providers`	ModelProvider resources (one per LLM API subscription)
`providers`	Provider resources
`secrets`	Pai-managed Kubernetes Secrets
`skills`	Skill bundles
`metrics`	Token usage and request metrics
`events <name>`	Events for a specific task agent

Flag	Description
`--agent <name>`	Filter task agents by Agent name
`--phase <phase>`	Filter task agents by phase
`--event-type <type>`	Filter events by type
`-n, --namespace <ns>`	Target a specific namespace

Examples:

# List all agents (service and task types)
pai get agents

# Describe a specific agent
pai get agent my-agent

# List task agents only (sessions alias)
pai get sessions

# Filter task agents
pai get sessions --agent openclaw --phase Running

# Describe a specific task agent
pai get agent fix-bug-42

# List model providers (preferred)
pai get model-providers

# Describe a specific model provider
pai get model-provider anthropic

# List providers
pai get providers

# Describe a specific provider
pai get provider github-writer

# List skills
pai get skills

# Show metrics
pai get metrics

# Show events for a task agent
pai get events fix-bug-42 --event-type agent.message

Example output (pai get agents):

NAME               TYPE      STATUS    MODELS          TOKENS/DAY   URL / TASK                              AGE
my-agent           service   Running   gemini-flash    12,450       https://a7x3k9.pairun.dev              2h
data-analyst       service   Running   claude-sonnet   3,200        https://b2m4p7.pairun.dev              1d
fix-bug-42         task      Complete  claude-sonnet   4,120        Fix the null pointer in auth…           10m
research-abc       task      Running   gemini-flash    1,800        Summarize Q1 reports                    2m

Example output (pai get sessions):

NAME             AGENT-DEFINITION   PHASE      TOKENS   TASK
fix-bug-42       openclaw           Complete   4,120    Fix the null pointer in auth middleware
research-abc     researcher         Running    1,800    Summarize Q1 reports

`pai delete`

Delete a Pai resource by type and name.

pai delete <type> <name>

Type	Description
`agent`	Agent resource (any mode). `session` is accepted as an alias for task agents
`model-provider`	ModelProvider
`provider`	Provider
`secret`	Kubernetes Secret
`skill`	Skill bundle

Examples:

pai delete agent my-agent
pai delete agent fix-bug-42     # delete a task agent
pai delete agent openclaw       # delete a template agent
pai delete model-provider anthropic
pai delete provider github-writer
pai delete secret gemini-key
pai delete skill coding-guidelines

`pai logs`

Stream or tail logs from an agent or session.

pai logs <name> [--tail N] [--follow | --no-follow]

Flag	Description
`--tail N`	Number of recent lines to show (default: 50)
`--follow, -f`	Follow log output — streams until Ctrl-C (default)
`--no-follow`	Print tail and exit

Works for both service and task agents — pass the agent name directly.

Examples:

# Tail agent logs (live follow)
pai logs my-agent

# Last 100 lines, then exit
pai logs my-agent --tail 100 --no-follow

# Stream task agent logs
pai logs fix-bug-42

`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 claude`

Drop into an interactive Claude Code session inside a running agent container.

pai claude <name>

Example:

pai claude openclaw-a7x3k9

`pai chat`

Interactive chat with a running task agent. Sends user.message events and streams agent responses in real time.

pai chat <name>

Special input	Description
`/interrupt`	Send an interrupt signal to the agent
`/exit` or `/quit`	Exit the chat

Example:

pai chat fix-bug-42

  Session chat  fix-bug-42  (openclaw)
  Started with: Fix the null pointer in auth middleware
  Type a message and press Enter. Ctrl-C or /exit to quit.

  ❯ What files have you modified so far?

  Agent  I've modified auth/middleware.go — fixed the nil check on line 42...

`pai cp`

Copy files between the local filesystem and an agent container. Uses agent:path syntax to reference a remote path.

pai cp <src> <dst>

Examples:

# Download from agent to local
pai cp my-agent:/workspace/output.json ./output.json

# Upload from local to agent
pai cp ./data.csv my-agent:/workspace/data.csv

`pai relay`

Bridge a local Chrome browser to a browser-relay agent via Chrome DevTools Protocol (CDP).

pai relay <name> --token <tok> [--chrome-port <port>]

Flag	Description
`--token <tok>`	Authentication token for the relay agent
`--chrome-port <port>`	Local Chrome remote-debugging port (default: 9222)

`pai scaling`

Show the autoscaling status and metric targets for an agent.

pai scaling <name> [--watch]

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

Examples:

pai scaling my-agent
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.

`pai audit`

View or verify the tamper-evident HMAC-SHA256 audit chain for an agent. pai audit aggregates events from two sources and returns them merged by timestamp:

Sidecar chain — one chain per agent pod, written by the pai-binding-proxy sidecar. Contains SERVICE_CALL, POLICY_DENY, PASSTHROUGH, and EXEC events. Stored on a dedicated PVC inaccessible from the agent container.
Gateway chain — one chain shared across the whole platform, written by pai-gateway. Contains LLM_CALL, TOOL_CALL, BUDGET_EXCEEDED, and GUARD.VIOLATION_* / GUARD.UNAVAILABLE events.

Each event carries a source field (sidecar or gateway) and a source_seq preserving its original position in its native chain. The merged seq is presentation-only.

pai audit <name> [--verify] [--limit N] [--since 1h|24h] [--type PATTERN] [--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
`--type PATTERN`	Filter by event type. Case-insensitive substring match; comma-separated for multiple. Examples: `--type guard`, `--type llm_call`, `--type llm_call,guard`. Filter runs before the `--limit` slice, so `--limit 20 --type guard` returns up to 20 guard events.
`--format json`	Output raw JSONL instead of pretty-printed table

Examples:

pai audit my-agent                                      # recent 50 events, mixed
pai audit my-agent --verify                             # verify sidecar chain integrity
pai audit my-agent --since 1h --format json             # JSON output, last hour
pai audit my-agent --type guard                         # only prompt-injection events
pai audit my-agent --type guard.violation_enforce       # only blocked requests
pai audit my-agent --type llm_call,guard                # LLM calls + all guard events
pai audit my-agent --type service_call,policy_deny      # sidecar provider events

Event types:

Type	Source	When
`EXEC`	sidecar	Process started inside the agent container
`SERVICE_CALL`	sidecar	Provider API call routed through the sidecar (GitHub, AWS, …)
`POLICY_DENY`	sidecar	Provider policy blocked a request with HTTP 403
`PASSTHROUGH`	sidecar	Request forwarded to a non-provider host
`LLM_CALL`	gateway	Agent→LLM provider call via `pai-gateway`
`TOOL_CALL`	gateway	Tool invocation extracted from an LLM response
`BUDGET_EXCEEDED`	gateway	Daily token budget hit; request rejected
`GUARD.VIOLATION_ENFORCE`	gateway	Request blocked by a GuardBinding in `enforce` mode
`GUARD.VIOLATION_AUDIT`	gateway	Guard flagged content; forwarded because binding is in `audit` mode
`GUARD.UNAVAILABLE`	gateway	Classifier unreachable — request forwarded (fail-open) + event logged

Example output:

  #   TIMESTAMP              EVENT                     DETAIL
 2026-04-14 14:18:30    SERVICE_CALL              google-oauth  oauth:token  /token ✓
 2026-04-14 14:18:45    LLM_CALL                  jane  claude-sonnet-4-6  in=1460 out=94  2683ms
 2026-04-14 14:20:10    GUARD.VIOLATION_AUDIT     prompt-guard-audit  prompt  injection=1.0000  "Forget everything above..."
 2026-04-14 14:20:13    LLM_CALL                  jane  claude-sonnet-4-6  in=1532 out=94  3002ms

Chain integrity

--verify only verifies the sidecar chain (per-agent HMAC key). Gateway chain verification is a platform-wide operation exposed on the gateway's /audit/verify endpoint — it's not scoped to a single agent.

`pai eval`

List, describe, and trigger Evals — quality test suites that run an agent against a curated set of fixtures and gate edits behind a passing run.

pai apply -f and pai delete eval <name> already work generically; this subcommand adds the eval-specific verbs (formatted listing + triggering runs with a --wait mode usable from CI).

pai eval list
pai eval get <name>
pai eval run <name> [--wait] [--timeout SECONDS]

Subcommands:

Command	Description
`list` (or `ls`)	Table of evals: name, target agent, last score, pass/total, result, last-run timestamp
`get <name>` (or `describe`, `show`)	One eval's status with the latest per-fixture results inline
`run <name>`	Trigger an eval run; returns immediately. Use `--wait` to block until terminal.

Flags (run):

Flag	Description
`--wait`	Block until the eval reaches Pass / Fail. Exits 0 on Pass, 1 on Fail, 2 on timeout. Useful in CI to gate releases.
`--timeout SECONDS`	How long to wait when `--wait` is set (default 600s)
`-n, --namespace`	Override the namespace from your context

Examples:

# List every eval in your namespace
pai eval list

# Show one eval's status + per-fixture results
pai eval get math-tutor-eval

# Trigger an eval run, return immediately
pai eval run math-tutor-eval

# Block until terminal — usable in CI/CD scripts
pai eval run math-tutor-eval --wait

# Tighter timeout for fast suites
pai eval run math-tutor-eval --wait --timeout 120

Example output (pai eval list):

  Evals

  NAME                TARGET         SCORE    PASS/TOTAL   RESULT   LAST-RUN
  ───────────────────────────────────────────────────────────────────────────
  math-tutor-eval     math-tutor     1.00     2/2          Pass     2026-05-05T19:51:40
  support-bot-eval    support-bot    0.78     7/9          Fail     2026-05-05T18:50:36

Example output (pai eval get):

  math-tutor-eval  eval

  Phase                    Passed
  Target agent             math-tutor
  Last result              Pass
  Last score               1.00
  Pass/Fail/Total          2 / 0 / 2
  Last run                 2026-05-05T19:51:40Z
  Run duration             11s
  Judge model              anthropic/claude-haiku-4-5

  Fixture results:

  FIXTURE              SCORE    RESULT   SEVERITY   MESSAGE
  ───────────────────────────────────────────────────────────────────────────
  tutor-add            1.00     Pass     medium     all 4 assertions passed
  tutor-multiply       1.00     Pass     medium     all 3 assertions passed

CI integration

Pair pai eval run --wait with the --timeout flag in a CI pipeline to block a release on a passing eval suite. The exit codes (0 Pass, 1 Fail, 2 timeout) line up with conventional shell semantics, so a one-liner like pai eval run release-suite --wait --timeout 600 || exit 1 is enough to gate downstream steps.

`pai config`

Manage CLI configuration and user environment variables.

pai config set <key> <value>
pai config get <key>
pai config list

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

Local config (`set` / `get` / `list`)

Stores arbitrary key-value pairs in ~/.pai/config.json.

pai config set default_namespace my-team
pai config get default_namespace
pai config list

User env vars (`set-env` / `unset-env` / `list-env`)

Manage env vars that are automatically injected into every agent pod you create. Values are stored on your PaiAccessToken in Kubernetes — they persist across machines and CLI reinstalls.

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 admin token`

Manage platform access tokens. Requires an admin token (targetNamespace: "*").

pai admin token create --namespace <ns> [--description <d>] [--expires <iso>]
pai admin token list
pai admin token revoke <name>

Flag	Description
`--namespace, -n <ns>`	Target namespace for the token; `` grants admin access (required* for create)
`--description, -d <d>`	Human-readable description
`--expires <iso>`	Expiry date in ISO-8601 format

Examples:

# Create a scoped token for team "platform"
pai admin token create --namespace platform --description "platform team CI"

# Create an admin token
pai admin token create --namespace "*" --description "admin"

# List all tokens
pai admin token list

# Revoke a token
pai admin token revoke tok-abc123

caution

Tokens are shown only once at creation time. Store them securely.

`pai version`

Print the Pai CLI version.

pai version

Example output:

pai v0.2.0

Commands​

pai login​

pai logout​

pai context​

pai run​

pai create​

From YAML​

pai create skill​

pai create model-provider​

pai create secret​

pai create provider​

pai apply​

pai get​

pai delete​

pai logs​

pai exec​

pai claude​

pai chat​

pai cp​

pai relay​

pai scaling​

pai audit​

pai eval​

pai config​

Local config (set / get / list)​

User env vars (set-env / unset-env / list-env)​

pai admin token​

pai version​

Commands

`pai login`

`pai logout`

`pai context`

`pai run`

`pai create`

From YAML

`pai create skill`

`pai create model-provider`

`pai create secret`

`pai create provider`

`pai apply`

`pai get`

`pai delete`

`pai logs`

`pai exec`

`pai claude`

`pai chat`

`pai cp`

`pai relay`

`pai scaling`

`pai audit`

`pai eval`

`pai config`

Local config (`set` / `get` / `list`)

User env vars (`set-env` / `unset-env` / `list-env`)

`pai admin token`

`pai version`