CLI

The everruns CLI provides a command-line interface for managing agents, sessions, and conversations. It’s useful for scripting, automation, and quick interactions without using the web UI.

Installation

Homebrew (macOS / Linux)

brew tap everruns/tap
brew install everruns

Cargo

Install from the Git repository:

cargo install --git https://github.com/everruns/everruns everruns-cli

Or clone and build locally:

git clone https://github.com/everruns/everruns.git
cd everruns
cargo install --path crates/cli

Verify

everruns --version

Configuration

The CLI connects to the Everruns API. By default, it uses the hosted API at https://app.everruns.com/api.

For local development, configure the API URL:

# Via command-line flag
everruns --api-url http://localhost:9300/api agents list

# Via environment variable
export EVERRUNS_API_URL=http://localhost:9300/api
everruns agents list

Default: https://app.everruns.com/api

Commands

Agents

Manage agent configurations.

Create Agent

# Inline creation
everruns agents create \
  --name "my-agent" \
  --system-prompt "You are a helpful assistant." \
  --tag production

# From YAML file
everruns agents create -f agent.yaml

# From JSON file
everruns agents create -f agent.json

# From Markdown with front matter
everruns agents create -f agent.md

YAML file format (agent.yaml):

name: "research-assistant"
description: "Helps with research tasks"
system_prompt: |
  You are a helpful research assistant.
  Always cite your sources.
capabilities:
  - ref: current_time
    config: {}
  - ref: web_fetch
    config: {}
tags:
  - research
  - assistant

For backward compatibility, you can also use the shorthand format:

capabilities:
  - current_time
  - web_fetch

The full format with ref and config allows per-agent capability configuration:

capabilities:
  - ref: filesystem
    config:
      allowed_paths: ["/home/user/projects"]
  - ref: web_browser
    config: {}

Markdown file format (agent.md):

---
name: "research-assistant"
description: "Helps with research tasks"
capabilities:
  - ref: current_time
    config: {}
  - ref: web_fetch
    config: {}
tags:
  - research
---
You are a helpful research assistant.

Always cite your sources and provide accurate information.

The markdown body becomes the system prompt. Both the full format (ref + config) and shorthand (just capability ID) are supported in markdown files.

List Agents

everruns agents list

Output:

ID                                    NAME              STATUS
agt_550e8400e29b41d4a716446655440000  research-bot      active
agt_660e8400e29b41d4a716446655440001  joke-bot          active

Get Agent

everruns agents get agt_xxx

Delete Agent

everruns agents delete agt_xxx

Capabilities

List available capabilities that can be assigned to agents.

# List available capabilities
everruns capabilities

# List all including coming soon
everruns capabilities --status all

# List only coming soon
everruns capabilities --status coming_soon

Output:

ID                    NAME               STATUS      CATEGORY
current_time          Current Time       available   Utilities
web_fetch             Web Fetch          available   Network
session_file_system   File System        available   File Operations
stateless_todo_list   Task Management    available   Productivity

Sessions

Manage conversation sessions for an agent.

Create Session

everruns sessions create --agent agt_xxx

# With title
everruns sessions create --agent agt_xxx --title "Debug session"

List Sessions

everruns sessions list

Get Session

everruns sessions get ses_xxx

Chat

Send a message and receive the agent’s response.

everruns chat "Tell me a joke!" --session ses_xxx

Output:

You: Tell me a joke!

Agent: Why don't scientists trust atoms? Because they make up everything!

Options:

• --timeout <seconds> - Max wait time for response (default: 300)
• --no-stream - Send message and exit without waiting for response

Output Formats

The CLI supports multiple output formats for scripting:

# Default text format
everruns agents list

# JSON format
everruns agents list --output json

# YAML format
everruns agents list --output yaml

Quiet Mode

Suppress non-essential output:

# Only output the created agent ID
everruns agents create -f agent.yaml --quiet
# Output: agt_550e8400e29b41d4a716446655440000

Examples

Complete Workflow

# 1. Create an agent and extract ID with jq
AGENT_ID=$(everruns agents create \
  --name "assistant" \
  --system-prompt "You are a helpful assistant." \
  -o json | jq -r '.id')

# 2. Create a session
SESSION_ID=$(everruns sessions create --agent $AGENT_ID -o json | jq -r '.id')

# 3. Chat with the agent
everruns chat "What time is it?" --session $SESSION_ID

Using Agent Files

# Create agent.md
cat > agent.md << 'EOF'
---
name: "code-reviewer"
description: "Reviews code and suggests improvements"
capabilities:
  - ref: current_time
    config: {}
  - ref: filesystem
    config:
      allowed_paths: ["/workspace"]
tags:
  - development
---
You are an expert code reviewer.

When reviewing code:
1. Check for bugs and edge cases
2. Suggest performance improvements
3. Ensure code follows best practices
EOF

# Create the agent
everruns agents create -f agent.md

JSON Output for Scripting

# Get agent details as JSON and extract with jq
everruns agents get agt_xxx --output json | jq '.tags'

# List agents and filter
everruns agents list --output json | jq '.data[] | select(.status == "active")'