PromptRails CLI

Command-line interface for PromptRails — the AI agent orchestration platform.

Installation

Homebrew (macOS / Linux)

brew tap promptrails/tap
brew install promptrails

Go Install

go install github.com/promptrails/cli/cmd/promptrails@latest

Binary Download

Download the latest release from the releases page.

Quick Start

# Interactive setup
promptrails init

# Or non-interactive (CI/CD)
promptrails init --api-key pr_key_...

# Check current context
promptrails status

Commands

Setup

promptrails init              # Set up CLI with API key
promptrails status            # Show current auth & workspace context
promptrails version           # Show CLI version

Agents

promptrails agent list                                  # List agents
promptrails agent list --type workflow                  # Filter by type (agent | workflow)
promptrails agent get <id>                              # Get details
promptrails agent create --name "My Agent" --type agent # Create (type: agent | workflow)
promptrails agent update <id> --name "New Name"         # Update
promptrails agent delete <id>                           # Delete
promptrails agent execute <id> --input '{"q": "hello"}'
promptrails agent versions <id>                         # List versions
promptrails agent promote <id> <version-id>             # Set current version

Agents come in exactly two kinds: agent (a single prompt, optionally extended with tools and sub-agents) and workflow (a deterministic DAG). Model, sampling, run budget, approval policy and attached tools live on the agent version, not on the agent or the prompt.

Prompts

promptrails prompt list
promptrails prompt get <id>
promptrails prompt create --name "My Prompt"
promptrails prompt versions <id>
promptrails prompt promote <id> <version-id>

Prompts are content-only (system/user text + input schema). To run a prompt, attach it to an agent version and execute the agent.

Executions

promptrails execution list                       # List executions
promptrails execution list --agent <id>          # Filter by agent
promptrails execution list --status waiting_approval
promptrails execution get <id>                   # Get details
promptrails execution tree <id>                  # Show the full sub-execution tree
promptrails execution cancel <id>                # Request cooperative cancellation

Approvals (execution-scoped)

Approval-gated tool calls park the execution at waiting_approval. Resolve them from the execution itself:

promptrails execution approval-inbox             # List runs waiting on approval
promptrails execution approve <id> --reason "ok" # Approve and resume
promptrails execution deny <id> --reason "no"    # Deny and resume with a denial

Credentials

promptrails credential list
promptrails credential create --provider openai --name "Production"
promptrails credential delete <id>
promptrails credential check <id>

API Keys

promptrails apikey list
promptrails apikey create --name "CI"     # Displays the key once
promptrails apikey delete <id>

Traces

promptrails trace summary                         # Aggregate token/cost/latency stats
promptrails trace summary --from 2026-07-01 --to 2026-07-31 --agent <id>
promptrails trace list                            # List trace spans
promptrails trace list --kind llm                 # Filter by span kind
promptrails trace get <trace-id>                  # All spans for a trace ID

Assets

promptrails assets list                          # List all assets
promptrails assets list --type image             # Filter by type
promptrails assets get <id>                      # Get details
promptrails assets signed-url <id>               # Get download URL
promptrails assets delete <id>                   # Delete

Agent Triggers

promptrails agent-trigger list
promptrails at get <trigger-id>
promptrails at create --name "GitHub" --agent-id <id> --source generic
promptrails at create --name "Slack #ops" --agent-id <id> --source slack
promptrails at update <trigger-id> --active
promptrails at delete <trigger-id>

The --source flag selects the inbound channel — generic (default), slack, telegram, whatsapp, teams, or schedule. The legacy webhook-trigger / wt command names still work as aliases.

Shell Completion

promptrails completion bash > /etc/bash_completion.d/promptrails
promptrails completion zsh  > "${fpath[1]}/_promptrails"
promptrails completion fish > ~/.config/fish/completions/promptrails.fish

Global Flags

Flag	Description
-o, --output	Output format: table (default) or json
--workspace	Override workspace ID for this command
--api-url	Override API base URL
--no-color	Disable color output

Environment Variables

Variable	Description
PROMPTRAILS_API_KEY	API key (overrides stored credentials)
PROMPTRAILS_WORKSPACE_ID	Workspace ID override
PROMPTRAILS_API_URL	API base URL override

Config Files

Stored in ~/.promptrails/:

File	Permissions	Contents
config.json	0644	API URL, active workspace, output format
credentials.json	0600	API key

License

MIT