# CLI

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

Source: https://0.0.0.0:8080/docs/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.

<div style={{ display: 'flex', gap: '0.75rem', marginBottom: '0.5rem' }}>
  <a href="https://github.com/promptrails/cli" target="_blank" rel="noopener noreferrer">
    GitHub
  </a>
</div>

## Installation

```bash
# 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:

```bash
promptrails version
```

## Authentication

### Initialize Configuration

```bash
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):

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

### Other Commands

```bash
# Check CLI and API status
promptrails status

# Show CLI version
promptrails version
```

## Output Formats

The CLI supports two output formats:

### Table (default)

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

```bash
promptrails agent list --output json
```

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

## Shell Completions

Generate shell completion scripts:

```bash
# 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

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

```yaml
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`) |

## Related Topics

- [API Keys and Scopes](/docs/api-keys-and-scopes) -- Creating API keys for CLI use
- [Python SDK](/docs/python-sdk) -- Python alternative for scripting
- [JavaScript SDK](/docs/javascript-sdk) -- JavaScript alternative
- [Go SDK](/docs/go-sdk) -- Go alternative