Agent Infra CLI

infra is a command-line client built on agent-infra-sdk. Infra services use the Agent Infra Gateway. File and command operations go through Environment Computer and Space APIs.

Install

cargo install agent-infra-cli --version 0.5.0

Since 0.3.0 the CLI follows the SDK's Environment-only boundary: use infra computer, infra space, and infra evaluate. Removed infra workspace commands are not remapped to legacy routes.

The default Gateway is http://127.0.0.1:5200. Persist a remote Gateway once:

infra config gateway set https://infra.example.com
infra config gateway get

Resolution order is --gateway > SKY_GATEWAY_URL > saved config > local default. Override the config path with --config or AGENT_INFRA_CONFIG. The default path is:

• macOS: ~/Library/Application Support/agent-infra/config.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/agent-infra/config.json
• Windows: %APPDATA%\agent-infra\config.json

Environment configuration remains supported:

export SKY_GATEWAY_URL=https://infra.example.com
export SKY_GATEWAY_TOKEN=...

Do not put a long-lived token directly on the command line in shared shell environments; process arguments and shell history may be visible to others. The config file stores only the Gateway URL, never credentials.

Sky credentials

Credential resolution order is --token > SKY_GATEWAY_TOKEN > a directly readable local ~/.sky/credentials token. Inspect discovery without printing secrets:

infra auth status

Modern sky login credentials use an ENCv1 encrypted store. Infra detects that login state but deliberately does not decrypt another CLI's credential file. In that case, issue a scoped Sky user API token and expose it as SKY_GATEWAY_TOKEN. infra auth status reports this as sky_login_encrypted and provides the same guidance.

Examples

# Health and discovery
infra gateway ready
infra gateway wait-ready --deadline 60
infra gateway discovery --output json

# Agent Registry
infra agent list --status active --limit 20
infra agent get agt_01K...
infra agent create --name weather --runtime-id rti_01K...
infra agent create --file create-agent.json

# Runtime Identity lifecycle
infra runtime create --name code-dev
infra runtime get rti_01K...
infra runtime rename rti_01K... code-staging --expected-revision 1
infra runtime activate rti_01K... --file activate-runtime.json
infra runtime permissions rti_01K... --file runtime-permissions.json
infra runtime bootstrap-credential --file runtime-bootstrap.json
infra runtime credential ensure rti_01K...
infra runtime credential exec rti_01K... -- cargo run -p agent-runtime-cli -- serve --config config/runtime.local.toml
infra runtime credential list rti_01K...
infra runtime credential rotate rti_01K... rti_rc_...
infra runtime credential revoke rti_01K... rti_rc_...
infra runtime revoke rti_01K... --file revoke-runtime.json

# Agents are configurations bound to Runtime IDs; reverse lookup stays here
infra agent list --related-runtime-id rti_01K...

# Durable context; append accepts an array of ConversationRecord objects
infra context recent conversation-1 --limit 50 --role user,assistant
infra context append --file messages.json

# Langfuse-backed trace metrics (repeat --project-id to query multiple projects)
infra trace metrics token-usage --project-id project-a --days 7
infra trace metrics model-breakdown --project-id project-a --data-source auto
infra trace metrics latency --days 30 --output json

# Allocate/query Langfuse projects through the Trace admin API
infra trace langfuse-project create --file create-langfuse-project.json \
  --idempotency-key allocate-langfuse-agt_weather
infra trace langfuse-project list --related-agent-id agt_weather
infra trace langfuse-project get project-id

# Runtime Langfuse binding (product path; not Admin)
infra trace binding get rti_01K...
infra trace binding initialize rti_01K... --project-name weather --idempotency-key init-trace-rti_01K...

# Environment computers, spaces, and snapshots
infra computer list
infra space list
infra snapshot create --provider moulin --idempotency-key snap-1
infra snapshot list

# Deploy runtime templates and bound repositories
infra deploy template list
infra deploy repo init --file create-runtime-repository.json --idempotency-key init-weather \
  --agent-id agt_weather --runtime-id rt-weather
infra deploy repo init --file create-runtime-repository.json --idempotency-key init-weather \
  --dir ./weather --no-clone
infra deploy repo list --owner-kind user --owner-id user-1
infra deploy repo get rrepo-1

# Initialize a runtime, agent, repo, trace binding, context, and default model
infra init --name weather --template-id rtpl-1 --no-clone
infra init --name weather --template-id rtpl-1 --dir ./weather

# OpenAI-compatible Model Infra JSON APIs; '-' means stdin
infra model models
infra model chat --file request.json
printf '%s' '{"model":"default","input":"hello"}' | infra model responses

Complex write requests are supplied as JSON files or standard input so the CLI stays aligned with the SDK's contract types as those contracts evolve. JSON field names use the contracts' camelCase wire format.

infra deploy repo init clones the bound GitLab repository with the operator's local Git credentials and writes a gitignored .env.local containing RREPO_ID, REPOSITORY_URL, and optional AGENT_ID / RUNTIME_ID. Pass --dir to choose the checkout path and --no-clone to write the env file without cloning. JSON stdout remains the repository record; the checkout path is printed on stderr. Tokens are never written to .env.local.

infra runtime create prints the complete CreateRuntimeIdentityResponse. On the first successful create this includes the one-time bootstrapToken; treat stdout as secret-bearing output and do not write it to shared logs. After permissions are installed and the identity is active, runtime bootstrap-credential exchanges that proof through the public Gateway bootstrap endpoint. Its JSON output also contains a secret workload token.

infra runtime credential ensure creates or reuses a durable Recovery Credential for an already-active Runtime Identity. The plaintext secret is stored in the OS keychain (service agent-infra.runtime-recovery) or, with --store file --yes, a 0600 file under ~/.agent-infra/recovery-credentials. credential exec injects AGENT_INFRA_RECOVERY_CREDENTIAL into a child process and never prints the secret. Do not write recovery secrets to .local.env, shell history, or logs.

The common create path takes a mutable name directly and defaults kind to code. The service derives a deterministic idempotency key from the normalized creation name, so callers normally do not pass one:

infra runtime create --name code-dev
infra runtime create --name tool-dev --kind tool

infra agent create --name weather --runtime-id rti_01K... is the common Agent path. The Registry derives an idempotency key from the normalized name unless --idempotency-key is passed. Creation still requires at least one Runtime ID. The --file form remains available for extra relations.

runtime_id remains stable when the name changes:

infra runtime rename rti_01K... code-staging --expected-revision 1

Use --idempotency-key only to control an exceptional retry scope. The advanced --file form remains available for a complete request document:

{
  "name": "code-dev",
  "kind": "code",
  "metadata": {}
}

Lifecycle commands (activate, suspend, resume, and revoke) accept a TransitionIdentityRequest document:

{
  "expectedRevision": 1,
  "idempotencyKey": "activate-runtime-01",
  "reason": "runtime provisioning completed"
}