CLI

Use the command line to manage PromptRails resources, automate setup, and inspect runs from scripts or CI.

Best for

Engineers building against the API, SDKs, CLI, MCP, or local tooling

The PromptRails CLI provides command-line access to all major platform features. Use it for scripting, CI/CD pipelines, and quick operations from your terminal.

GitHub

Installation

# macOS (Homebrew)
brew install promptrails/tap/promptrails
 
# Download binary from GitHub releases
# Replace OS and ARCH with your platform (e.g., darwin-arm64, linux-amd64)
curl -sL https://github.com/promptrails/cli/releases/latest/download/promptrails-OS-ARCH.tar.gz | tar xz
sudo mv promptrails /usr/local/bin/

Verify installation:

promptrails version

Authentication

Initialize Configuration

promptrails init

This creates configuration files at ~/.promptrails/config.json and ~/.promptrails/credentials.json, prompting for your API URL and API key.

Environment Variables

You can also authenticate via environment variables (useful for CI/CD):

export PROMPTRAILS_API_KEY="your-api-key"
export PROMPTRAILS_API_URL="https://api.promptrails.ai"

Environment variables take precedence over the config file.

Technical detailsCommand reference

Commands

Agent Commands

# List agents
promptrails agent list
 
# Get agent details
promptrails agent get <agent-id>
 
# Create an agent
promptrails agent create --name "My Agent" --type simple
 
# Execute an agent
promptrails agent execute <agent-id> --input '{"message": "Hello"}'
 
# List agent versions
promptrails agent versions <agent-id>
 
# Promote a version
promptrails agent promote <agent-id> <version-id>

Prompt Commands

# List prompts
promptrails prompt list
 
# Get prompt details
promptrails prompt get <prompt-id>
 
# Create a prompt
promptrails prompt create --name "Summarizer"
 
# Execute a prompt
promptrails prompt execute <prompt-id> --input '{"text": "Long text..."}'
 
# List versions
promptrails prompt versions <prompt-id>

Execution Commands

# List recent executions
promptrails execution list
 
# Get execution details
promptrails execution get <execution-id>
 
# Filter by agent
promptrails execution list --agent-id <agent-id>
 
# Filter by status
promptrails execution list --status completed

Credential Commands

# List credentials
promptrails credential list
 
# Create a credential
promptrails credential create \
  --name "OpenAI Key" \
  --category llm \
  --type openai \
  --value "sk-..."
 
# Check a credential's validity
promptrails credential check <credential-id>
 
# Delete a credential
promptrails credential delete <credential-id>

Webhook Trigger Commands

# List triggers
promptrails webhook-trigger list
 
# Create a trigger
promptrails webhook-trigger create \
  --agent-id <agent-id> \
  --name "Deploy Trigger"
 
# Activate/deactivate
promptrails webhook-trigger activate <trigger-id>
promptrails webhook-trigger deactivate <trigger-id>

Workspace Commands

# Show current workspace (determined by API key)
promptrails workspace current

Other Commands

# Check CLI and API status
promptrails status
 
# Show CLI version
promptrails version

Output Formats

Use table output for humans scanning the terminal and JSON output when scripts or CI need to parse results.

Technical detailsOutput formats and shell completions

The CLI supports two output formats:

Table (default)

promptrails agent list

ID                          NAME                   TYPE        STATUS
2NxAbc123def456ghi789jkl    Customer Support       simple      active
2NxBbc456def789ghi012jkl    Data Pipeline          chain       active
2NxCbc789def012ghi345jkl    Multi-Agent System     multi_agent archived

JSON

promptrails agent list --output json

{
  "data": [
    {
      "id": "2NxAbc123def456ghi789jkl",
      "name": "Customer Support",
      "type": "simple",
      "status": "active"
    }
  ]
}

Shell Completions

Generate shell completion scripts:

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

Technical detailsAutomation and environment reference

CI/CD Usage

GitHub Actions Example

name: Execute Agent
on:
  push:
    branches: [main]
 
jobs:
  execute:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: |
          curl -sL https://github.com/promptrails/cli/releases/latest/download/promptrails-linux-amd64.tar.gz | tar xz
          sudo mv promptrails /usr/local/bin/
 
      - name: Execute agent
        env:
          PROMPTRAILS_API_KEY: ${{ secrets.PROMPTRAILS_API_KEY }}
        run: |
          promptrails agent execute ${{ vars.AGENT_ID }} \
            --input '{"branch": "${{ github.ref_name }}", "commit": "${{ github.sha }}"}' \
            --output json

GitLab CI Example

execute-agent:
  image: ubuntu:latest
  variables:
    PROMPTRAILS_API_KEY: $PROMPTRAILS_API_KEY
  script:
    - apt-get update && apt-get install -y curl
    - curl -sL https://github.com/promptrails/cli/releases/latest/download/promptrails-linux-amd64.tar.gz | tar xz
    - mv promptrails /usr/local/bin/
    - promptrails agent execute $AGENT_ID --input '{"event": "deploy"}'

Environment Variables Reference

Variable	Description
`PROMPTRAILS_API_KEY`	API key for authentication
`PROMPTRAILS_API_URL`	API base URL (default: `https://api.promptrails.ai`)

API Keys and Scopes -- Creating API keys for CLI use
Python SDK -- Python alternative for scripting
JavaScript SDK -- JavaScript alternative
Go SDK -- Go alternative

CLI