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]

Run herdctl --version to print the installed version, and herdctl --help (or herdctl <command> --help) for built-in help.

Commands

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)

Options:

Option	Description
-y, --yes	Accept all defaults without prompting (requires an explicit subcommand: init fleet or init agent <name>)
-f, --force	Overwrite existing files

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. Generates agents/<name>/agent.yaml and appends a reference to herdctl.yaml.

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, delegate, dontAsk
--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

start

Start the fleet. Runs in the foreground, streaming fleet logs to stdout until you press Ctrl+C. Writes a PID file to the state directory (.herdctl/herdctl.pid) that herdctl stop uses.

herdctl start [options]

Options:

Option	Description
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)
-v, --verbose	Enable verbose debug logging (sets HERDCTL_LOG_LEVEL=debug)
--web	Enable the web dashboard
--web-port <port>	Web dashboard port (default: 3232)

Examples:

# Start the fleet (all agents)
herdctl start

# Start with verbose debug output
herdctl start --verbose

# Start with web dashboard
herdctl start --web

# Start with web dashboard on a custom port
herdctl start --web --web-port 8080

# Use a specific config file
herdctl start --config ./fleets/prod/herdctl.yaml

Note

herdctl start starts the whole fleet — there is no flag to start a single agent. To run one agent on demand, use herdctl trigger.

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 the running fleet process. Reads the PID file from the state directory, sends SIGTERM, and waits for graceful shutdown. If the timeout is reached, the process is force-killed with SIGKILL.

herdctl stop [options]

Options:

Option	Description
-f, --force	Immediate stop — send SIGKILL right away (cancels running jobs)
-t, --timeout <seconds>	Wait max seconds for graceful shutdown before force kill (default: 30)
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# Graceful stop (waits up to 30s)
herdctl stop

# Wait up to 60 seconds before force killing
herdctl stop --timeout 60

# Immediate force stop
herdctl stop --force

Note

herdctl stop stops the entire fleet process — it takes no agent argument. To stop a single running job, use herdctl cancel.

status

Show fleet status or details for a specific agent.

herdctl status [agent] [options]

Arguments:

Argument	Description
agent	Agent name (optional — use qualified name for sub-fleet agents)

Options:

Option	Description
--json	Output as JSON for scripting
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

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

# JSON output for scripting
herdctl status --json

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

logs

Show agent logs, or logs for a specific job.

herdctl logs [agent] [options]

Options:

Option	Description
-f, --follow	Follow log output continuously
--job <id>	Logs from a specific job
-n, --lines <count>	Number of lines to show (default: 50)
--json	Output as newline-delimited JSON (one log entry per line)
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# Recent logs from all agents
herdctl logs

# View recent logs for one agent
herdctl logs price-checker

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

# Show the last 200 lines
herdctl logs price-checker -n 200

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

# Newline-delimited JSON for scripting
herdctl logs --json

trigger

Manually trigger an agent to run a job. By default the agent’s output is streamed to the terminal as it runs, then a job summary is printed.

herdctl trigger <agent> [options]

Arguments:

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

Options:

Option	Description
-S, --schedule <name>	Trigger a specific schedule defined for the agent
-p, --prompt <prompt>	Custom prompt (overrides the schedule/default prompt)
-w, --wait	Wait for the job to complete and stream job output
-q, --quiet	Suppress output display (just show job info)
--json	Output as JSON for scripting
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# Trigger with the agent's default prompt
herdctl trigger price-checker

# Trigger a specific schedule
herdctl trigger price-checker -S daily-check

# 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

# Wait for completion and stream job output
herdctl trigger my-agent --wait

# Quiet mode - no streamed output, just job info
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
I'll check the current prices for office chairs at Staples and IKEA.

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

Job completed
Job ID:   job-2024-01-15-abc123
Agent:    price-checker

Run 'herdctl logs --job job-2024-01-15-abc123' to view detailed logs.

If nothing was streamed, the agent’s final output is displayed after completion (truncated at 20,000 characters if needed). Use --quiet to suppress output entirely.

With --wait, pressing Ctrl+C exits with code 130 but the job keeps running in the background.

Hooks:

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

Executing 1 after_run hook(s) for event: completed
Discord hook completed successfully in 245ms: channel 123456789012345678 (204)
Hook execution complete: 1 succeeded, 0 failed, 0 skipped (245ms)

jobs

List recent jobs, with filtering and a configurable limit.

herdctl jobs [options]

Options:

Option	Description
-a, --agent <name>	Filter by agent name
-S, --status <status>	Filter by status: pending, running, completed, failed, cancelled
-l, --limit <count>	Number of jobs to show (default: 20)
--json	Output as JSON for scripting
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# List the 20 most recent jobs
herdctl jobs

# Jobs for a specific agent
herdctl jobs --agent price-checker

# Only running jobs
herdctl jobs --status running

# Show more history
herdctl jobs --limit 50

# JSON output for scripting
herdctl jobs --json

job

Show details for a single job.

herdctl job <id> [options]

Arguments:

Argument	Description
id	Job ID

Options:

Option	Description
-L, --logs	Also show the job’s output
--json	Output as JSON for scripting
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# Show job details
herdctl job job-2024-01-15-abc123

# Include the job's output
herdctl job job-2024-01-15-abc123 --logs

# JSON output for scripting
herdctl job job-2024-01-15-abc123 --json

cancel

Cancel a running (or pending) job. By default this shows the job details and asks for interactive confirmation before cancelling — use --yes in scripts to skip the prompt.

herdctl cancel <id> [options]

Arguments:

Argument	Description
id	ID of the job to cancel

Options:

Option	Description
-f, --force	Force cancel — shortens the graceful-termination window to 1 second before SIGKILL (a normal cancel allows 10 seconds)
-y, --yes	Skip the confirmation prompt (for scripted use)
--json	Output as JSON for scripting (also skips the interactive prompt)
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

Examples:

# Cancel a job (prompts for confirmation)
herdctl cancel job-2024-01-15-abc123

# Cancel without confirmation (scripts/CI)
herdctl cancel job-2024-01-15-abc123 --yes

# Force cancel with SIGKILL
herdctl cancel job-2024-01-15-abc123 --force --yes

# JSON output for scripting
herdctl cancel job-2024-01-15-abc123 --json

Only jobs with status running or pending can be cancelled; attempting to cancel a finished job exits with an error.

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
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

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] [options]

Arguments:

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

Options:

Option	Description
-c, --config <path>	Path to config file or directory
-s, --state <path>	Path to state directory (default: .herdctl)

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 an 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.

The agent command group accepts a shared option:

Option	Description
-c, --config <path>	Path to config file or directory (applies to all agent subcommands)

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>	Override installation directory (default: ./agents/<name>/)
--dry-run	Preview changes without installing
-f, --force	Overwrite existing agent directory

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 agents in the fleet. When the fleet has sub-fleets, output is a tree grouped by fleet hierarchy; otherwise it’s a flat table.

herdctl agent list [options]

Options:

Option	Description
--json	Output as JSON for scripting

Examples:

# List all agents
herdctl agent list

# Output:
# Name                Source                                   Version  Installed     Status
# ------------------------------------------------------------------------------------------
# competitor-tracker  user/competitive-analysis-agent          1.0.0    Jan 13, 2024  installed
# github-triager      manual                                   -        -             manual

# JSON output for scripting
herdctl agent list --json

agent info

Show detailed information about an agent.

herdctl agent info <name> [options]

Arguments:

Argument	Description
name	Name of the agent

Options:

Option	Description
--json	Output as JSON for scripting

Examples:

# Show agent details
herdctl agent info competitor-tracker

# Output:
# Agent: competitor-tracker
# Description: Competitive intelligence for Acme SaaS Platform
# Status: Installed (via GitHub)
# Source: https://github.com/edspencer/competitive-analysis-agent
# Version: 1.0.0
# Installed: 2024-01-13T10:00:00.000Z
#
# Schedules:
#   daily-competitive-scan: cron (0 8 * * *)
#
# Environment Variables:
#   Required:
#     COMPETITOR_WEBSITES
#
# Files:
#   agent.yaml
#   CLAUDE.md
#
# Workspace: agents/competitor-tracker/workspace/

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

agent remove

Remove an installed agent from the fleet.

herdctl agent remove <name> [options]

Arguments:

Argument	Description
name	Name of the agent to remove

Options:

Option	Description
-f, --force	Reserved for future use — currently a no-op (removal does not prompt for confirmation)
--keep-workspace	Preserve the workspace directory while removing the agent

Examples:

# Remove an agent (no confirmation prompt — removes immediately)
herdctl agent remove competitor-tracker

# 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)

Caution

agent remove deletes the agent directory immediately, without an interactive confirmation. The --force flag is currently a reserved no-op kept for a future interactive confirmation flow.

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

config

Configuration management commands.

config validate

Validate the current configuration (fleet config plus all referenced agent configs). Exits with code 0 if valid, 1 if not.

herdctl config validate [options]

Options:

Option	Description
--fix	Show suggestions for fixing validation errors
-c, --config <path>	Path to config file or directory

Examples:

# Validate the configuration in the current directory
herdctl config validate

# Validate with fix suggestions
herdctl config validate --fix

# Validate a specific config file
herdctl config validate --config ./fleets/prod/herdctl.yaml

On success, prints the fleet name, config path, and the list of resolved agents. On failure, prints schema/YAML/environment-variable errors (with suggested fixes when --fix is set).

config show

Show the merged/resolved configuration — fleet info, defaults, and every resolved agent with its schedules and tool permissions.

herdctl config show [options]

Options:

Option	Description
--json	Output as JSON
-c, --config <path>	Path to config file or directory

Examples:

# Human-readable resolved config
herdctl config show

# Full resolved config as JSON
herdctl config show --json

Common Options

There are no global options other than --version and --help — options like -c and -v are defined per command. Most commands share these:

Option	Description	Available on
-c, --config <path>	Path to config file or directory	Most commands (see each command’s table)
-s, --state <path>	Path to state directory (default: .herdctl)	start, stop, status, logs, trigger, jobs, job, cancel, sessions
--json	Machine-readable output for scripting	status, logs, trigger, jobs, job, cancel, sessions, agent list, agent info, config show
-v, --verbose	Verbose output	start (debug logging), sessions (full resume commands)

Exit Codes

Code	Meaning
0	Success
1	General error (config not found, agent not found, job failed, etc.)
130	Interrupted by signal (128 + SIGINT signal number 2)

trigger --wait propagates the job’s success or failure through its exit code. Interrupting trigger --wait or logs --follow with Ctrl+C exits with 130; a job being waited on continues running in the background.

Environment Variables

Variable	Description
HERDCTL_LOG_LEVEL	Log level: debug, info, warn, error (default: info; start --verbose sets debug)
NO_COLOR	Disable colored output (see no-color.org)
FORCE_COLOR	Force colored output even when not a TTY
ANTHROPIC_API_KEY	Claude API key, passed through to agent runs (Docker isolation requires it; local runs can also use your existing Claude Code authentication)

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

Agent configs can reference arbitrary environment variables with ${VAR} interpolation — herdctl agent info <name> lists the variables an installed agent requires.

Configuration Files

herdctl looks for configuration in this order:

1. Path specified with -c / --config
2. herdctl.yaml (or herdctl.yml) found by walking up the directory tree from the current directory

Agent definitions live in files referenced from herdctl.yaml (conventionally ./agents/<name>/agent.yaml).

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