CLI Reference

The herdctl CLI provides commands for managing and interacting with your agent fleet.

Installation

# Install globally
npm install -g herdctl

# Or use via npx
npx herdctl [command]

Commands

trigger

Manually trigger an agent to run a job.

herdctl trigger <agent-name> [options]

Arguments:

Argument	Description
agent-name	Name of the agent to trigger (use qualified name for sub-fleet agents)

Options:

Option	Description
-p, --prompt <text>	Prompt to send to the agent (uses default_prompt if not specified)
-q, --quiet	Suppress streaming output during execution
--json	Output result in JSON format

Examples:

# Trigger with default prompt (if agent has default_prompt configured)
herdctl trigger price-checker

# Trigger with custom prompt
herdctl trigger hurricane-watcher --prompt "Check for storms near Miami"

# Trigger a sub-fleet agent using qualified name
herdctl trigger herdctl.security-auditor

# Quiet mode - no streaming, just final result
herdctl trigger my-agent -q

# JSON output for scripting
herdctl trigger my-agent --json

Streaming Output:

By default, the trigger command streams the agent’s output in real-time:

$ herdctl trigger price-checker
Triggering agent: price-checker
Job started: job-2024-01-15-abc123

I'll check the current prices for office chairs at Staples and IKEA.

First, let me fetch the Staples Hyken chair page...
[...]

**Price Check Complete**: Staples Hyken at $159.99 (best deal, meets $200 target).
IKEA MARKUS at $299.99. Buy here: https://www.staples.com/...

Job completed successfully in 45.2s

Output Display:

After job completion, the agent’s final output is displayed (truncated at 20,000 characters if needed). Use --quiet to suppress this.

Hooks:

If the agent has hooks configured, they run after the job completes. Hook execution is logged:

Running hook: Price alert (discord)
Hook completed: Price alert

status

Show the status of agents and running jobs.

herdctl status [agent-name]

Examples:

# Show all agents
herdctl status

# Show specific agent
herdctl status price-checker

# Show sub-fleet agent using qualified name
herdctl status herdctl.security-auditor

When using fleet composition, status output groups agents by their fleet hierarchy.

logs

View logs for agents or specific jobs.

herdctl logs [agent-name] [options]

Options:

Option	Description
-f, --follow	Stream logs in real-time
--job <id>	Show logs for specific job
-n, --lines <count>	Number of lines to show (default: 100)

Examples:

# View recent logs
herdctl logs price-checker

# Follow logs in real-time
herdctl logs price-checker -f

# View specific job logs
herdctl logs --job job-2024-01-15-abc123

start

Start the fleet daemon to run scheduled jobs and optional web dashboard.

herdctl start [options]

Options:

Option	Description
-d, --daemon	Run in background
-v, --verbose	Enable debug-level logging (sets HERDCTL_LOG_LEVEL=debug)
--agent <name>	Start specific agent only
--web	Enable the web dashboard
--web-port <port>	Web dashboard port (default: 3232)

Examples:

# Start all agents
herdctl start

# Start in background
herdctl start -d

# Start specific agent
herdctl start --agent price-checker

# Start with verbose debug output
herdctl start --verbose

# Start with web dashboard
herdctl start --web

Zero-Config Mode:

When no herdctl.yaml configuration file is found, herdctl start automatically launches in web-only mode. This enables session browsing without any fleet configuration:

# Start web dashboard without fleet config
npx herdctl start

# Output:
# No fleet configuration found — starting web UI only.
# Browse your Claude Code sessions at http://localhost:3232

In web-only mode, you can:

• Browse all Claude Code sessions from ~/.claude/ on your machine
• View session details and conversation history
• Resume CLI sessions as ad hoc chats
• Use the All Chats page to discover sessions across all projects

This is particularly useful when you want to explore and interact with your Claude Code sessions without setting up a full herdctl fleet.

stop

Stop running agents.

herdctl stop [agent-name]

Examples:

# Stop all agents
herdctl stop

# Stop specific agent
herdctl stop price-checker

cancel

Cancel a running job.

herdctl cancel <job-id>

Arguments:

Argument	Description
job-id	ID of the job to cancel

Examples:

# Cancel a specific job
herdctl cancel job-2024-01-15-abc123

validate

Validate configuration files.

herdctl validate [path]

Examples:

# Validate all configuration
herdctl validate

# Validate specific agent
herdctl validate agents/my-agent.yaml

init

Initialize a new fleet or add an agent. Running herdctl init without a subcommand launches an interactive selector.

herdctl init           # Interactive: choose fleet or agent
herdctl init fleet     # Create a new herdctl.yaml
herdctl init agent     # Add a new agent (interactive)

init fleet

Create a new herdctl.yaml fleet configuration and .herdctl/ state directory.

herdctl init fleet [options]

Options:

Option	Description
-n, --name <name>	Fleet name (defaults to directory name)
-f, --force	Overwrite existing configuration

Examples:

# Initialize with default name
herdctl init fleet

# Initialize with a specific fleet name
herdctl init fleet --name my-fleet

init agent

Add a new agent to the fleet via an interactive wizard or flags.

herdctl init agent [name] [options]

Arguments:

Argument	Description
name	Agent name (optional — prompted if not given)

Options:

Option	Description
-d, --description <desc>	Agent description
--permission-mode <mode>	Permission mode (default, acceptEdits, bypassPermissions, plan)
--docker / --no-docker	Enable or disable Docker isolation
--runtime <runtime>	Runtime backend (sdk or cli)
--discord	Add Discord chat integration
--slack	Add Slack chat integration
-y, --yes	Skip all prompts, use defaults
-f, --force	Overwrite existing agent file

Examples:

# Interactive agent creation
herdctl init agent

# Create agent with a name (still prompts for other options)
herdctl init agent price-checker

# Fully non-interactive
herdctl init agent price-checker --yes --runtime cli --docker

# With chat integrations
herdctl init agent my-bot --discord --slack --yes

sessions

List and manage Claude Code sessions for your agents. When agents run with session persistence enabled, herdctl tracks their Claude Code session IDs, making them discoverable and resumable.

herdctl sessions [options]

Options:

Option	Description
-a, --agent <name>	Filter sessions by agent name
-v, --verbose	Show full resume commands for each session
--json	Output as JSON for scripting

Examples:

# List all sessions
herdctl sessions

# Output:
# Sessions (2)
# ══════════════════════════════════════════════════════════════════════════════
# AGENT               SESSION ID                               LAST ACTIVE   JOBS
# ──────────────────────────────────────────────────────────────────────────────
# bragdoc-developer   a166a1e4-c89e-41f8-80c8-d73f6cd0d39c     5m ago        19
# price-checker       b234e5f6-a78b-49c0-d12e-3456789abcde     2h ago        3

# Filter by agent
herdctl sessions --agent bragdoc-developer

# Show full resume commands
herdctl sessions --verbose

# JSON output for scripting
herdctl sessions --json

sessions resume

Resume a Claude Code session interactively. This launches Claude Code with the --resume flag in the agent’s configured workspace directory.

herdctl sessions resume [session-id]

Arguments:

Argument	Description
session-id	Session ID, partial ID, or agent name (optional - defaults to most recent)

Behavior:

• If no argument is provided, resumes the most recently active session
• Supports partial session ID matching (e.g., a166a1e4 matches a166a1e4-c89e-41f8-80c8-d73f6cd0d39c)
• Accepts agent name to resume that agent’s session
• Automatically changes to the agent’s workspace directory before launching Claude

Examples:

# Resume the most recent session
herdctl sessions resume

# Resume by full session ID
herdctl sessions resume a166a1e4-c89e-41f8-80c8-d73f6cd0d39c

# Resume by partial session ID
herdctl sessions resume a166a1e4

# Resume by agent name
herdctl sessions resume bragdoc-developer

Output:

Resuming session for bragdoc-developer (19 jobs, last active 5m ago)
Session: a166a1e4-c89e-41f8-80c8-d73f6cd0d39c
Workspace: /path/to/project

Running: claude --resume a166a1e4-c89e-41f8-80c8-d73f6cd0d39c
     in: /path/to/project

Tip

The sessions resume command is particularly useful for picking up where a Discord bot or scheduled agent left off, allowing you to continue the conversation interactively.

See Sessions for more about session modes and persistence.

agent

Manage distributable agents — install from GitHub or local paths, list installed agents, and remove agents you no longer need.

agent add

Install an agent from GitHub or a local path.

herdctl agent add <source> [options]

Arguments:

Argument	Description
source	Agent source: github:user/repo[@ref] or ./local/path

Options:

Option	Description
--path <path>	Install to specific directory (default: ./agents/<name>/)
--dry-run	Show what would be installed without making changes
--force	Overwrite existing agent if it exists

Examples:

# Install from GitHub
herdctl agent add github:edspencer/competitive-analysis-agent

# Install specific version
herdctl agent add github:edspencer/competitive-analysis-agent@v1.0.0

# Install from a branch
herdctl agent add github:edspencer/competitive-analysis-agent@main

# Install from local directory
herdctl agent add ./my-local-agent

# Preview installation without making changes
herdctl agent add github:user/repo --dry-run

# Overwrite existing agent
herdctl agent add github:user/repo --force

# Install to custom path
herdctl agent add github:user/repo --path ./agents/my-custom-name

Output:

After installation, the command displays:

• Files installed and their locations
• Fleet config changes made
• Required environment variables to configure
• Next steps for testing the agent

agent list

List all installed agents.

herdctl agent list [options]

Options:

Option	Description
--json	Output as JSON for scripting

Examples:

# List all installed agents
herdctl agent list

# Output:
# NAME                  SOURCE                                      VERSION  INSTALLED
# competitor-tracker    github:user/competitive-analysis-agent      1.0.0    2 days ago
# content-writer        github:user/content-agent                   0.5.0    1 week ago
# github-triager        ./agents/custom-triager                     -        3 days ago

# JSON output for scripting
herdctl agent list --json

agent info

Show detailed information about an installed agent.

herdctl agent info <name> [options]

Arguments:

Argument	Description
name	Name of the installed agent

Options:

Option	Description
--json	Output as JSON for scripting

Examples:

# Show agent details
herdctl agent info competitor-tracker

# Output:
# Name: competitor-tracker
# Description: Competitive intelligence for Acme SaaS Platform
# Source: github:edspencer/competitive-analysis-agent
# Version: 1.0.0
# Installed: 2 days ago
#
# Files:
#   ./agents/competitor-tracker/
#     agent.yaml
#     CLAUDE.md
#     knowledge/ (3 files)
#     workspace/
#
# Environment variables:
#   COMPETITOR_WEBSITES
#   DISCORD_WEBHOOK_URL
#   SLACK_CHANNEL
#
# Schedules:
#   daily-competitive-scan (0 8 * * *)

# JSON output
herdctl agent info competitor-tracker --json

agent remove

Remove an installed agent.

herdctl agent remove <name> [options]

Arguments:

Argument	Description
name	Name of the agent to remove

Options:

Option	Description
--force	Skip confirmation prompt
--keep-workspace	Preserve workspace data while removing agent

Examples:

# Remove an agent (prompts for confirmation)
herdctl agent remove competitor-tracker

# Remove without confirmation
herdctl agent remove competitor-tracker --force

# Remove but keep workspace data
herdctl agent remove competitor-tracker --keep-workspace

The removal process:

1. Removes the agent directory from ./agents/
2. Removes the agent reference from herdctl.yaml
3. Lists environment variables that were used (for manual cleanup)

See Installing Agents for a complete guide to the agent distribution system.

Global Options

These options work with all commands:

Option	Description
-c, --config <path>	Path to herdctl.yaml (default: ./herdctl.yaml)
-v, --verbose	Enable verbose output
--version	Show version number
--help	Show help

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Agent error
4	Job error

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Required. Claude API key
HERDCTL_CONFIG	Path to config file (alternative to -c)
HERDCTL_LOG_LEVEL	Log level: debug, info, warn, error
NO_COLOR	Disable colored output (see no-color.org)
FORCE_COLOR	Force colored output even when not a TTY

Additional environment variables may be required for integrations:

Variable	Description
GITHUB_TOKEN	GitHub API access for work sources
DISCORD_BOT_TOKEN	Discord bot token for notifications/chat
DISCORD_CHANNEL_ID	Default Discord channel for notifications

Configuration Files

herdctl looks for configuration in this order:

1. Path specified with -c / --config
2. HERDCTL_CONFIG environment variable
3. ./herdctl.yaml in current directory
4. ./agents/*.yaml for agent definitions

See Fleet Configuration and Agent Configuration for details.

Related Pages

• Getting Started — First-time setup guide
• Agent Configuration — Agent YAML reference
• Sessions — Session modes and persistence
• Hooks — Post-job notifications and actions
• Triggers — How jobs are started