CLI

Manage PromptRails from the command line with the official CLI for agents, prompts, executions, credentials, and more.

CLI

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.

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

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

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

CLI