talonctl reference

talonctl is the management CLI for talond. Use it to inspect a running daemon, scaffold config, manage personas and channels, test providers, work with schedules, and inspect thread/provider state.

All examples use npx talonctl ..., but talonctl ... works the same way when the binary is installed globally. Commands that read config default to talond.yaml, and .env is loaded automatically before config parsing.

Commands at a glance

Command	Purpose
status	Show daemon health, active containers, and queue depth
reload	Hot-reload configuration without restarting
migrate	Apply database migrations
backup	Back up database, config, personas, and skills
doctor	Check system requirements and configuration
setup	Generate a starter config and data directory
add-channel	Add a channel connector to talond.yaml
list-channels	List configured channels
remove-channel	Remove a channel from talond.yaml
add-persona	Scaffold a persona and add it to config
list-personas	List configured personas
remove-persona	Remove a persona and its bindings
bind	Bind a persona to a channel
unbind	Remove a persona-channel binding
list-capabilities	List valid capability labels
set-capabilities	Show or modify capability grants on a persona
add-skill	Scaffold a skill and attach it to a persona
list-skills	List all skills or filter by persona
add-mcp	Add an MCP server to a skill
env-check	Audit ${ENV_VAR} usage in config
auth-mcp	Authenticate with an MCP server over HTTP using OAuth 2.0
config-show	Print effective config with secrets masked by default
queue-purge	Purge queue items by status
chat	Connect to the terminal channel
list-providers	List configured providers in foreground and background contexts
add-provider	Add a provider to agentRunner, backgroundAgent, or both
set-default-provider	Change the default provider for one context
test-provider	Run a provider smoke test
list-threads	List persisted threads for a channel
reset-provider-affinity	Reset provider affinity for one thread or a whole channel
add-schedule	Create a scheduled task
list-schedules	List scheduled tasks
remove-schedule	Delete a scheduled task permanently
run-subagent	Invoke a sub-agent without a running daemon
whatsapp-auth	Scan a QR code and save Baileys credentials
a2a list	List A2A tasks
a2a send	Submit a manual A2A task

Daemon operations

status

Shows daemon health, active containers, and queue depth over IPC.

npx talonctl status
npx talonctl status --ipc-dir ./data/ipc/daemon --timeout 8000

Usage

talonctl status [--ipc-dir <path>] [--timeout <ms>]

Option	Description	Default
--ipc-dir <path>	IPC directory used to reach the daemon	from config
--timeout <ms>	IPC response timeout	5000

reload

Reloads config, personas, skills, and channel setup without restarting the daemon.

npx talonctl reload
npx talonctl reload --ipc-dir ./data/ipc/daemon --timeout 8000

Usage

talonctl reload [--ipc-dir <path>] [--timeout <ms>]

Option	Description	Default
--ipc-dir <path>	IPC directory used to reach the daemon	from config
--timeout <ms>	IPC response timeout	5000

chat

Connects to Talon’s terminal channel over WebSocket. Requires a running terminal connector and a token supplied with --token or TERMINAL_TOKEN.

export TERMINAL_TOKEN=your-secret-token

npx talonctl chat --host 127.0.0.1 --port 7700
npx talonctl chat --host 10.0.1.95 --port 7700 --persona researcher
npx talonctl chat --host talond.example.com --port 443 --tls --client-id laptop

Usage

talonctl chat [--host <host>] [--port <port>] [--token <token>] [--client-id <id>] [--persona <name>] [--tls]

Option	Description	Default
--host <host>	Terminal connector host	127.0.0.1
--port <port>	Terminal connector port	7700
--token <token>	Authentication token	TERMINAL_TOKEN if set
--client-id <id>	Stable client identity for thread persistence	auto-generated
--persona <name>	Override the channel’s default persona	channel default
--tls	Use wss:// instead of ws://	off

Setup and maintenance

setup

Creates a first-pass talond.yaml and data directory after checking the local environment.

npx talonctl setup
npx talonctl setup --config talond.yaml --data-dir data

Usage

talonctl setup [--config <path>] [--data-dir <path>]

Option	Description	Default
--config <path>	Where to write talond.yaml	talond.yaml
--data-dir <path>	Data directory path	data

doctor

Runs environment and configuration checks before you start the daemon or after a config change.

npx talonctl doctor
npx talonctl doctor --config ./talond.yaml

Usage

talonctl doctor [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

migrate

Applies pending SQLite schema migrations. No daemon is required.

npx talonctl migrate
npx talonctl migrate --config ./talond.yaml

Usage

talonctl migrate [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

backup

Creates a backup containing the database, config, personas, and skills.

npx talonctl backup
npx talonctl backup --config ./talond.yaml --output /backups/talon-2026-04-03

Usage

talonctl backup [--config <path>] [--output <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml
--output <path>	Backup output directory	auto-generated

queue-purge

Purges queue rows by status through the daemon IPC layer. By default it removes pending, failed, and completed.

npx talonctl queue-purge
npx talonctl queue-purge --statuses dead_letter,failed
npx talonctl queue-purge --all

Usage

talonctl queue-purge [--ipc-dir <path>] [--timeout <ms>] [--statuses <list>] [--all]

Option	Description	Default
--ipc-dir <path>	IPC directory used to reach the daemon	from config
--timeout <ms>	IPC response timeout	5000
--statuses <list>	Comma-separated list of statuses to purge	pending,failed,completed
--all	Purge every status, including in-flight items	off

Configuration inspection

env-check

Finds ${ENV_VAR} placeholders referenced by config and reports which ones are missing.

npx talonctl env-check
npx talonctl env-check --config ./talond.yaml

Usage

talonctl env-check [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

auth-mcp

Authenticate with an MCP server over HTTP using OAuth 2.0. Supports login, logout, and status subcommands.

npx talonctl auth-mcp login --server https://mcp.example.com --client-id talon --client-secret $MCP_SECRET --token-url https://mcp.example.com/oauth/token --scopes read,write
npx talonctl auth-mcp status --server https://mcp.example.com
npx talonctl auth-mcp logout --server https://mcp.example.com

Usage

talonctl auth-mcp login --server <url> --client-id <id> --client-secret <secret> --token-url <url> [--scopes <list>]
talonctl auth-mcp status --server <url>
talonctl auth-mcp logout --server <url>

Option	Description	Default
login --server <url>	MCP server base URL	required
login --client-id <id>	OAuth client ID	required
login --client-secret <secret>	OAuth client secret	required
login --token-url <url>	OAuth token endpoint URL	required
login --scopes <list>	Comma-separated OAuth scopes	—
status --server <url>	MCP server base URL	required
logout --server <url>	MCP server base URL	required

config-show

Prints the effective config after env substitution. Secrets stay masked unless you explicitly opt out.

npx talonctl config-show
npx talonctl config-show --show-secrets

Usage

talonctl config-show [--config <path>] [--show-secrets]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml
--show-secrets	Show resolved secret values	off

Channels and bindings

add-channel

Adds a new channel entry to talond.yaml. The command scaffolds the channel record; you still need to provide channel-specific secrets in config.

npx talonctl add-channel --name my-telegram --type telegram
npx talonctl add-channel --name slack-engineer --type slack

Usage

talonctl add-channel --name <name> --type <type> [--config <path>]

Option	Description	Default
--name <name>	Unique channel name	required
--type <type>	Connector type such as telegram, slack, discord, whatsappBaileys, email, or terminal	required
--config <path>	Path to talond.yaml	talond.yaml

list-channels

Lists all configured channels.

npx talonctl list-channels

Usage

talonctl list-channels [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

remove-channel

Removes a channel from config. Existing bindings to that channel are removed with it.

npx talonctl remove-channel --name old-slack

Usage

talonctl remove-channel --name <name> [--config <path>]

Option	Description	Default
--name <name>	Channel to remove	required
--config <path>	Path to talond.yaml	talond.yaml

bind

Binds a persona to a channel. The first binding created for a channel becomes that channel’s default route.

npx talonctl bind --persona assistant --channel my-telegram

Usage

talonctl bind --persona <name> --channel <name> [--config <path>]

Option	Description	Default
--persona <name>	Persona name	required
--channel <name>	Channel name	required
--config <path>	Path to talond.yaml	talond.yaml

unbind

Removes a persona-channel binding.

npx talonctl unbind --persona assistant --channel my-telegram

Usage

talonctl unbind --persona <name> --channel <name> [--config <path>]

Option	Description	Default
--persona <name>	Persona name	required
--channel <name>	Channel name	required
--config <path>	Path to talond.yaml	talond.yaml

whatsapp-auth

Authenticates a WhatsApp Baileys connector by printing a QR code and saving the resulting credentials.

npx talonctl whatsapp-auth --auth-dir ./baileys-auth
npx talonctl whatsapp-auth --auth-dir ./baileys-auth --timeout 180

Usage

talonctl whatsapp-auth [--auth-dir <path>] [--timeout <seconds>]

Option	Description	Default
--auth-dir <path>	Directory used to store Baileys credentials	./baileys-auth
--timeout <seconds>	Seconds to wait for a QR scan	120

Personas, skills, and MCP

add-persona

Creates a persona directory and appends the persona to config. Optional flags let you set model, provider, skills, capabilities, and a starter prompt source in one step.

npx talonctl add-persona --name assistant
npx talonctl add-persona --name coder --model gpt-5.4 --provider codex-cli \
  --skills web-search,file-editing --capabilities "channel.send:terminal,subagent.invoke"

Usage

talonctl add-persona --name <name> [--config <path>] [--templates-dir <path>] [--model <model>] [--provider <provider>] [--capabilities <caps>] [--require-approval <caps>] [--skills <skills>] [--system-prompt-file <path>] [--description <text>]

Option	Description	Default
--name <name>	Persona name	required
--config <path>	Path to talond.yaml	talond.yaml
--templates-dir <path>	Template directory used for starter prompts	templates
--model <model>	Persona model name	unset
--provider <provider>	Provider override	unset
--capabilities <caps>	Comma-separated allow-list	unset
--require-approval <caps>	Comma-separated approval-gated capabilities	unset
--skills <skills>	Comma-separated skill names	unset
--system-prompt-file <path>	Existing Markdown file to use as system prompt	unset
--description <text>	Persona description written to frontmatter	unset

list-personas

Lists all configured personas.

npx talonctl list-personas

Usage

talonctl list-personas [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

remove-persona

Removes a persona from config and deletes its bindings.

npx talonctl remove-persona --name old-bot

Usage

talonctl remove-persona --name <name> [--config <path>]

Option	Description	Default
--name <name>	Persona to remove	required
--config <path>	Path to talond.yaml	talond.yaml

list-capabilities

Prints the capability labels Talon recognizes for persona configuration.

npx talonctl list-capabilities

Usage

talonctl list-capabilities

This command does not read talond.yaml, so it has no config flags.

set-capabilities

Shows or updates capability grants on an existing persona.

npx talonctl set-capabilities --persona assistant --show
npx talonctl set-capabilities --persona assistant --add "channel.send:my-telegram,subagent.invoke"
npx talonctl set-capabilities --persona assistant --remove "db.query:own"

Usage

talonctl set-capabilities --persona <name> [--allow <labels>] [--add <labels>] [--remove <labels>] [--require-approval <labels>] [--show] [--config <path>]

Option	Description	Default
--persona <name>	Persona name	required
--allow <labels>	Replace the allow list with a comma-separated set	unset
--add <labels>	Add labels to the allow list	unset
--remove <labels>	Remove labels from the allow list	unset
--require-approval <labels>	Replace requireApproval with a comma-separated set	unset
--show	Print current capabilities without modifying them	off
--config <path>	Path to talond.yaml	talond.yaml

add-skill

Creates a new skill and attaches it to a persona.

npx talonctl add-skill --name web-search --persona assistant
npx talonctl add-skill --name docs-writer --persona webmaster --format skillmd

Usage

talonctl add-skill --name <name> --persona <persona> [--format <format>] [--config <path>]

Option	Description	Default
--name <name>	Skill name	required
--persona <persona>	Persona that should receive the skill	required
--format <format>	Skill format: yaml or skillmd	yaml
--config <path>	Path to talond.yaml	talond.yaml

list-skills

Lists all configured skills or filters by persona.

npx talonctl list-skills
npx talonctl list-skills --persona assistant

Usage

talonctl list-skills [--persona <name>] [--config <path>]

Option	Description	Default
--persona <name>	Filter by persona name	all personas
--config <path>	Path to talond.yaml	talond.yaml

add-mcp

Adds an MCP server definition to a skill. stdio servers use --command; sse and http servers use --url.

npx talonctl add-mcp --skill web-search --name brave --transport stdio \
  --command node --args dist/server.js

npx talonctl add-mcp --skill docs --name public-api --transport http \
  --url https://api.example.com/mcp

Usage

talonctl add-mcp --skill <name> --name <name> --transport <type> [--command <cmd>] [--args <args...>] [--url <url>] [--env <pairs>] [--skills-dir <path>]

Option	Description	Default
--skill <name>	Skill name	required
--name <name>	MCP server name inside the skill	required
--transport <type>	stdio, sse, or http	required
--command <cmd>	Command to execute for stdio transport	unset
--args <args...>	Command arguments for stdio transport	unset
--url <url>	Server URL for sse or http transport	unset
--env <pairs>	Comma-separated KEY=VAL pairs	unset
--skills-dir <path>	Skills directory override	skills

Providers and thread affinity

list-providers

Lists configured providers from both agentRunner and backgroundAgent.

npx talonctl list-providers

Usage

talonctl list-providers [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

add-provider

Adds a provider to the foreground runner, background workers, or both.

npx talonctl add-provider --name gemini-cli --command gemini \
  --context both --context-window 1000000 --default-model gemini-2.5-pro --enabled

npx talonctl add-provider --name codex-cli --command codex \
  --context agent-runner --context-enabled true --trigger-metric cache_read_input_tokens \
  --threshold-ratio 0.8 --recent-message-count 10 --summarizer session-summarizer

Usage

talonctl add-provider --name <name> --command <cmd> [--context <ctx>] [--context-window <tokens>] [--context-enabled <enabled>] [--trigger-metric <metric>] [--threshold-ratio <ratio>] [--recent-message-count <count>] [--summarizer <name>] [--enabled] [--default-model <model>] [--config <path>]

Option	Description	Default
--name <name>	Provider name	required
--command <cmd>	CLI binary path	required
--context <ctx>	Target context: agent-runner, background, or both	both
--context-window <tokens>	Context window size in tokens	200000
--context-enabled <enabled>	Enable context management for agent-runner providers	unset
--trigger-metric <metric>	Rotation metric: input_tokens, cache_read_input_tokens, cache_creation_input_tokens, or cache_total_input_tokens	unset
--threshold-ratio <ratio>	Rotation threshold	0.5
--recent-message-count <count>	Verbatim messages kept after rotation	10
--summarizer <name>	Sub-agent used for session summaries	session-summarizer
--enabled	Enable the provider immediately	off
--default-model <model>	Set options.defaultModel	unset
--config <path>	Path to talond.yaml	talond.yaml

set-default-provider

Switches the default provider for either foreground runs or background workers.

npx talonctl set-default-provider --name codex-cli --context agent-runner
npx talonctl set-default-provider --name claude-code --context background

Usage

talonctl set-default-provider --name <name> --context <ctx> [--config <path>]

Option	Description	Default
--name <name>	Provider name to promote	required
--context <ctx>	agent-runner or background	required
--config <path>	Path to talond.yaml	talond.yaml

test-provider

Runs a minimal provider smoke test to confirm the binary is installed, authenticated, and usable.

npx talonctl test-provider --name claude-code
npx talonctl test-provider --name codex-cli --context background

Usage

talonctl test-provider --name <name> [--context <ctx>] [--config <path>]

Option	Description	Default
--name <name>	Provider name to test	required
--context <ctx>	agent-runner or background	agent-runner
--config <path>	Path to talond.yaml	talond.yaml

list-threads

Lists persisted threads for a channel, including connector-specific external IDs, latest provider, and latest activity.

npx talonctl list-threads --channel my-telegram

Usage

talonctl list-threads --channel <name> [--config <path>]

Option	Description	Default
--channel <name>	Channel name	required
--config <path>	Path to talond.yaml	talond.yaml

reset-provider-affinity

Clears sticky provider affinity so the next message goes through normal provider selection again. You can target one thread with --external-id or wipe an entire channel with --all.

npx talonctl reset-provider-affinity --channel my-telegram --external-id 123456789
npx talonctl reset-provider-affinity --channel slack-engineer --all --yes

Usage

talonctl reset-provider-affinity --channel <name> (--external-id <id> | --all) [--yes] [--config <path>]

Option	Description	Default
--channel <name>	Channel name	required
--external-id <id>	One thread’s connector-specific external ID	unset
--all	Reset every thread on the channel	off
--yes	Skip confirmation	off
--config <path>	Path to talond.yaml	talond.yaml

Connector-specific external IDs:

Connector	External ID format
Telegram	chat_id
Slack	<channelId>:<thread_ts> or <channelId>
Terminal	clientId
WhatsApp	sender wa_id
Email	<address>:<messageId>

Scheduling

add-schedule

Creates a durable cron-based scheduled task for a persona.

npx talonctl add-schedule --persona assistant --channel my-telegram \
  --cron "0 8 * * 1-5" --label "Morning briefing" \
  --prompt "Review my tasks and send a short morning briefing."

Usage

talonctl add-schedule --persona <name> --channel <name> --cron <expr> --label <label> --prompt <prompt> [--prompt-file <path>] [--config <path>]

Option	Description	Default
--persona <name>	Persona that owns the schedule	required
--channel <name>	Channel used for the scheduled thread	required
--cron <expr>	Five-field cron expression	required
--label <label>	Human-readable label	required
--prompt <prompt>	Prompt text sent on each run	required
--prompt-file <path>	Load the schedule’s system prompt from a file	—
--config <path>	Path to talond.yaml	talond.yaml

list-schedules

Lists all schedules or filters by persona.

npx talonctl list-schedules
npx talonctl list-schedules --persona assistant

Usage

talonctl list-schedules [--persona <name>] [--config <path>]

Option	Description	Default
--persona <name>	Filter by persona name	all personas
--config <path>	Path to talond.yaml	talond.yaml

remove-schedule

Deletes a scheduled task permanently. This command takes the schedule ID as a positional argument.

npx talonctl remove-schedule abc123

Usage

talonctl remove-schedule <schedule-id> [--config <path>]

Option	Description	Default
--config <path>	Path to talond.yaml	talond.yaml

Sub-agent testing

run-subagent

Runs a sub-agent directly without a daemon. This is useful for testing prompt design and JSON contracts in isolation.

npx talonctl run-subagent --name session-summarizer \
  --input '{"transcript":"User: Hi\nAssistant: Hello!"}'

npx talonctl run-subagent --name memory-retriever \
  --input '{"query":"deployment steps"}'

Usage

talonctl run-subagent --name <name> --input <json> [--config <path>] [--subagents-dir <path>]

Option	Description	Default
--name <name>	Sub-agent name	required
--input <json>	JSON payload passed to the sub-agent	required
--config <path>	Path to talond.yaml	talond.yaml
--subagents-dir <path>	Override the sub-agents directory	unset

A2A task tooling

a2a list

Lists A2A tasks with optional filters.

npx talonctl a2a list
npx talonctl a2a list --status working --target software-engineer --limit 50

Usage

talonctl a2a list [--status <state>] [--target <persona>] [--limit <n>] [--config <path>]

Option	Description	Default
--status <state>	Filter by submitted, working, completed, failed, or canceled	all states
--target <persona>	Filter by target persona	all personas
--limit <n>	Maximum number of rows to show	20
--config <path>	Path to talond.yaml	talond.yaml

a2a send

Submits a manual A2A task to another persona for testing or ops work.

npx talonctl a2a send software-engineer "Review the latest PR"
npx talonctl a2a send software-engineer "Run the smoke tests" --source james

Usage

talonctl a2a send <target-persona> <message> [--source <persona>] [--config <path>]

Option	Description	Default
--source <persona>	Source persona name recorded on the task	cli
--config <path>	Path to talond.yaml	talond.yaml