Skip to main content

CLI Reference

The distri CLI is the primary tool for developing, testing, and deploying agents. Install it to run agents locally, manage skills and workflows, or push agents to Distri Cloud.

Installation​

curl -fsSL https://distri.dev/install.sh | sh

Verify your installation:

distri --version

Agent Execution​

Interactive TUI​

# Launch the default agent
distri

# Launch a specific agent
distri tui my_agent

# Resume a previous conversation
distri tui my_agent --resume last
distri tui my_agent --resume <thread-id>

Opens an interactive terminal chat session with your agent.

Single task execution​

distri run --task "summarize this quarter's metrics" --agent my_agent

Runs the agent with a single task and exits when complete.

OptionDescription
--task "..."The task to execute (required)
--agent AGENTAgent name (defaults to workspace default)
--remoteRun on Distri Cloud instead of locally
--resume IDResume an existing thread
--context JSONAdditional context as JSON
--overrides JSONOverride agent config fields
--task-id IDAssign a specific task ID
--thread-id IDAssign a specific thread ID
--traceparent HEADERW3C traceparent header for distributed tracing

Example​

distri run --task "who is the prime minister of singapore" --agent search_agent
⏺ search({"query": "current prime minister of Singapore", "limit": 1})

⏺ The current Prime Minister of Singapore is Lawrence Wong.

Agent Management​

# List all agents in the workspace
distri agents list

# Push a single agent definition
distri agents push agents/my_agent.md

# Push all agent files in a directory
distri agents push agents/ --all

# Delete an agent (with confirmation)
distri agents delete my_agent

# Delete without confirmation prompt
distri agents delete my_agent -y

Skills​

Skills are reusable prompt snippets that agents can invoke.

# List workspace skills
distri skills list

# Include public/system skills
distri skills list --all

# Push a skill file
distri skills push skills/summarize.md

# Push all skills in a directory
distri skills push skills/ --all

Traces & Debugging​

# List recent traces (default 20)
distri traces list

# List more traces
distri traces list --limit 50

# Show trace detail with Gantt chart
distri traces show <trace-id>

# Filter to specific spans
distri traces show <trace-id> --span "llm"

# Verbose output with full span data
distri traces show <trace-id> -v

Threads​

# List conversation threads
distri threads list

Tools​

# List all available tools
distri tools list

# Filter tools by name
distri tools list --filter "search"

# List tools for a specific agent
distri tools list --agent my_agent

# Invoke a tool directly
distri tools invoke my_tool --input '{"query": "test"}'

# Invoke within a session
distri tools invoke my_tool --input '{"query": "test"}' --session <session-id>

Workflows​

# List workflows
distri workflows list

# Run a workflow
distri workflows run my_workflow

# Run step-by-step
distri workflows run my_workflow --step

# Run with input data
distri workflows run my_workflow --input '{"key": "value"}'

# Resume from a specific entry
distri workflows run my_workflow --entry <entry-id>

# Check workflow status
distri workflows status workflow.yaml

# Push a workflow definition
distri workflows push workflow.yaml

# Push with a custom name
distri workflows push workflow.yaml --name my_workflow

Resources​

Connections​

# List connections
distri connections list

# Get an OAuth token for a connection
distri connections token <connection-id>

Secrets​

# List secrets
distri secrets list

# Set a secret
distri secrets set MY_API_KEY sk-abc123

# Delete a secret
distri secrets delete MY_API_KEY

Prompts​

# List prompts
distri prompts list

# Push a prompt file
distri prompts push prompts/system.md

Auth & Profiles​

Login​

# Interactive login
distri login

# Login with email (skip browser)
distri login --email

# Skip workspace selection
distri login --skip-workspace

# Login to a named profile
distri login --profile staging

Profile management​

# List all profiles
distri profile list

# Switch active profile
distri profile use staging

# Show current profile
distri profile show

# Show a specific profile
distri profile show staging

# Delete a profile
distri profile delete staging

# Delete without confirmation
distri profile delete staging -y

# Set profile config values
distri profile config set --api-key <key>
distri profile config set --workspace-id <id>
distri profile config set --api-url https://custom.api.url

Server​

Start a local Distri server for development:

# Start with defaults
distri serve

# Custom host and port
distri serve --host 0.0.0.0 --port 9000

# Headless mode (no TUI)
distri serve --headless