CLI Command Reference

Detailed reference for all LibreFang CLI command groups: agents, hands, workflows, triggers, skills, channels, and configuration.

For an overview of the CLI, installation instructions, and global options, see the CLI Reference. For usage examples and guides, see CLI Examples & Guides.

Agent Commands

librefang agent new

Spawn an agent from a built-in template.

librefang agent new [<TEMPLATE>]

Arguments:

Argument	Description
`<TEMPLATE>`	Template name (e.g. `coder`, `assistant`, `researcher`). If omitted, displays an interactive picker listing all available templates.

Behavior:

Templates are discovered from: the repo agents/ directory (dev builds), ~/.librefang/workspaces/agents/ (assistant pre-installed, others installed from dashboard), and LIBREFANG_AGENTS_DIR (env override).
Each template is a directory containing an agent.toml manifest.
In daemon mode: sends POST /api/agents with the manifest. Agent is persistent.
In standalone mode: boots an in-process kernel. Agent is ephemeral.

Example:

# Interactive picker
librefang agent new

# Spawn by name
librefang agent new coder

# Spawn the assistant template
librefang agent new assistant

librefang agent spawn

Spawn an agent from a custom manifest file.

librefang agent spawn <MANIFEST>

Arguments:

Argument	Description
`<MANIFEST>`	Path to an agent manifest TOML file.

Behavior:

Reads and parses the TOML manifest file.
In daemon mode: sends the raw TOML to POST /api/agents.
In standalone mode: boots an in-process kernel and spawns the agent locally.

Example:

librefang agent spawn ./my-agent/agent.toml

librefang agent list

List all running agents.

librefang agent list [--json]

Options:

Option	Description
`--json`	Output as JSON array for scripting.

Output columns: ID, NAME, STATE, PROVIDER, MODEL (daemon mode) or ID, NAME, STATE, CREATED (in-process mode).

Example:

librefang agent list

librefang agent list --json | jq '.[].name'

librefang agent chat

Start an interactive chat session with a specific agent.

librefang agent chat <AGENT_ID>

Arguments:

Argument	Description
`<AGENT_ID>`	Agent UUID. Obtain from `librefang agent list`.

Behavior:

Opens a REPL-style chat loop.
Type messages at the you> prompt.
Agent responses display at the agent> prompt, followed by token usage and iteration count.
Type exit, quit, or press Ctrl+C to end the session.

Example:

librefang agent chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

librefang agent kill

Terminate a running agent.

librefang agent kill <AGENT_ID>

Arguments:

Argument	Description
`<AGENT_ID>`	Agent UUID to terminate.

Example:

librefang agent kill a1b2c3d4-e5f6-7890-abcd-ef1234567890

Hands are autonomous execution modules that give agents the ability to take actions in the real world — browsing the web, managing files, interacting with APIs, and more. All hand commands require a running daemon.

librefang hand list

List all available hands (bundled and installed).

librefang hand list

Output columns: ID, NAME, VERSION, STATUS, DESCRIPTION.

Discovers hands from ~/.librefang/workspaces/hands/ (pre-installed from registry on first boot). Users can activate hands from the dashboard.

librefang hand active

Show currently active hand instances and their runtime state.

librefang hand active

Output columns: INSTANCE ID, HAND ID, AGENT, STATE, STARTED.

librefang hand activate <name>

Activate a hand, making it available for agent use.

librefang hand activate <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID (e.g. `clip`, `lead`, `researcher`).

Example:

librefang hand activate clip
librefang hand activate researcher

librefang hand deactivate <name>

Deactivate a running hand, stopping its execution.

librefang hand deactivate <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID to deactivate.

Example:

librefang hand deactivate clip

librefang hand status [name]

Show active status for a specific hand or all active hands.

librefang hand status [<NAME>]

Arguments:

Argument	Description
`<NAME>`	Optional hand ID. If omitted, shows all active hands.

Example:

# Show all active hands
librefang hand status

# Show status for a specific hand
librefang hand status clip

librefang hand install <path>

Install a hand from a local directory containing a HAND.toml manifest.

librefang hand install <PATH>

Arguments:

Argument	Description
`<PATH>`	Path to the hand directory (must contain `HAND.toml`).

Example:

librefang hand install ./my-hand

librefang hand info <name>

Show detailed information about a hand including its capabilities, dependencies, and configuration.

librefang hand info <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID.

Example:

librefang hand info clip

librefang hand check-deps <name>

Check whether all required dependencies for a hand are installed.

librefang hand check-deps <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID.

Example:

librefang hand check-deps clip

librefang hand install-deps <name>

Install any missing dependencies required by a hand.

librefang hand install-deps <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID.

Example:

librefang hand install-deps clip

librefang hand pause <name>

Pause a running hand without fully deactivating it. The hand can be resumed later.

librefang hand pause <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID or instance ID.

Example:

librefang hand pause clip

librefang hand resume <name>

Resume a previously paused hand.

librefang hand resume <NAME>

Arguments:

Argument	Description
`<NAME>`	Hand ID or instance ID.

Example:

librefang hand resume clip

Workflow Commands

All workflow commands require a running daemon.

librefang workflow list

List all registered workflows.

librefang workflow list

Output columns: ID, NAME, STEPS, CREATED.

librefang workflow create

Create a workflow from a JSON definition file.

librefang workflow create <FILE>

Arguments:

Argument	Description
`<FILE>`	Path to a JSON file describing the workflow steps.

Example:

librefang workflow create ./my-workflow.json

librefang workflow run

Execute a workflow by ID.

librefang workflow run <WORKFLOW_ID> <INPUT>

Arguments:

Argument	Description
`<WORKFLOW_ID>`	Workflow UUID. Obtain from `librefang workflow list`.
`<INPUT>`	Input text to pass to the workflow.

Example:

librefang workflow run abc123 "Analyze this code for security issues"

Trigger Commands

All trigger commands require a running daemon.

librefang trigger list

List all event triggers.

librefang trigger list [--agent-id <ID>]

Options:

Option	Description
`--agent-id <ID>`	Filter triggers by the owning agent's UUID.

Output columns: TRIGGER ID, AGENT ID, ENABLED, FIRES, PATTERN.

librefang trigger create

Create an event trigger for an agent.

librefang trigger create <AGENT_ID> <PATTERN_JSON> [options]

Arguments:

Argument	Description
`<AGENT_ID>`	UUID of the agent that owns the trigger.
`<PATTERN_JSON>`	Trigger pattern as a JSON string (e.g. `'"lifecycle"'`).

Options:

Option	Default	Description
`--prompt <TEMPLATE>`	`"Event: {{event}}"`	Prompt template sent to the agent. Use `{{event}}` as placeholder.
`--max-fires <N>`	`0` (unlimited)	Maximum number of times the trigger can fire.
`--target-agent <ID>`	(owner)	Route the triggered message to a different agent instead of the owner.
`--cooldown <SECS>`	none	Minimum seconds between consecutive fires of this trigger.
`--session-mode <MODE>`	agent default	Override session mode for triggered invocations (`persistent` or `new`).

Pattern examples:

# Fire on any lifecycle event
librefang trigger create <AGENT_ID> '"lifecycle"'

# Fire when any agent is spawned
librefang trigger create <AGENT_ID> '"agent_spawned"'

# Fire on agent termination, max 5 times, 60s cooldown
librefang trigger create <AGENT_ID> '"agent_terminated"' --max-fires 5 --cooldown 60

# Fire on all events, route message to a different agent
librefang trigger create <AGENT_ID> '"all"' --target-agent <OTHER_AGENT_ID>

# Custom pattern JSON
librefang trigger create <AGENT_ID> '{"agent_spawned":{"name_pattern":"worker-*"}}'

librefang trigger get

Show all details of a single trigger.

librefang trigger get <TRIGGER_ID>

librefang trigger update

Partially update a trigger. Only the flags you supply are changed.

librefang trigger update <TRIGGER_ID> [options]

Options:

Option	Description
`--pattern <JSON>`	New event pattern (JSON string).
`--prompt <TEMPLATE>`	New prompt template.
`--enabled <true\|false>`	Enable or disable the trigger.
`--max-fires <N>`	New maximum fires limit.
`--cooldown <SECS>`	New cooldown in seconds.
`--clear-cooldown`	Remove the cooldown limit entirely.
`--session-mode <MODE>`	New session mode override (`persistent` or `new`).
`--clear-session-mode`	Remove the session mode override (revert to agent default).
`--target-agent <ID>`	Route the triggered message to a different agent (UUID).
`--clear-target-agent`	Remove the target agent override (revert to owner routing).

# Change prompt and set a 30s cooldown
librefang trigger update <TRIGGER_ID> --prompt "Alert: {{event}}" --cooldown 30

# Remove the cooldown
librefang trigger update <TRIGGER_ID> --clear-cooldown

# Switch to new-session mode
librefang trigger update <TRIGGER_ID> --session-mode new

# Redirect firing to a different agent
librefang trigger update <TRIGGER_ID> --target-agent <OTHER_AGENT_ID>

# Clear the target agent redirect
librefang trigger update <TRIGGER_ID> --clear-target-agent

librefang trigger enable / disable

Enable or disable a trigger without deleting it.

librefang trigger enable <TRIGGER_ID>
librefang trigger disable <TRIGGER_ID>

librefang trigger delete

Delete a trigger by ID.

librefang trigger delete <TRIGGER_ID>

Arguments:

Argument	Description
`<TRIGGER_ID>`	UUID of the trigger to delete.

Skill Commands

librefang skill list

List all installed skills.

librefang skill list

Output columns: NAME, VERSION, TOOLS, DESCRIPTION.

Loads skills from ~/.librefang/skills/ (installed from dashboard or user custom).

librefang skill install

Install a skill from a local directory, git URL, or FangHub marketplace.

librefang skill install <SOURCE>

Arguments:

Argument	Description
`<SOURCE>`	Skill name (FangHub), local directory path, or git URL.

Behavior:

Local directory: Looks for skill.toml in the directory. If not found, checks for OpenClaw-format skills (SKILL.md with YAML frontmatter) and auto-converts them.
Remote (FangHub): Fetches and installs from the FangHub marketplace. Skills pass through SHA256 verification and prompt injection scanning.

Example:

# Install from local directory
librefang skill install ./my-skill/

# Install from FangHub
librefang skill install web-search

# Install an OpenClaw-format skill
librefang skill install ./openclaw-skill/

librefang skill remove

Remove an installed skill.

librefang skill remove <NAME>

Arguments:

Argument	Description
`<NAME>`	Name of the skill to remove.

Example:

librefang skill remove web-search

librefang skill search

Search the FangHub marketplace for skills.

librefang skill search <QUERY>

Arguments:

Argument	Description
`<QUERY>`	Search query string.

Example:

librefang skill search "docker kubernetes"

librefang skill create

Interactively scaffold a new skill project.

librefang skill create

Behavior:

Prompts for:

Skill name
Description
Runtime (python, node, or wasm; defaults to python)

Creates a directory under ~/.librefang/skills/<name>/ with:

skill.toml -- manifest file
src/main.py (or src/index.js) -- entry point with boilerplate

Example:

librefang skill create
# Skill name: my-tool
# Description: A custom analysis tool
# Runtime (python/node/wasm) [python]: python

Channel Commands

librefang channel list

List configured channels and their status.

librefang channel list

Output columns: CHANNEL, ENV VAR, STATUS.

Checks config.toml for channel configuration sections and environment variables for required tokens. Status is one of: Ready, Missing env, Not configured.

Channels checked: webchat, telegram, discord, slack, whatsapp, signal, matrix, email.

librefang channel setup

Interactive setup wizard for a channel integration.

librefang channel setup [<CHANNEL>]

Arguments:

Argument	Description
`<CHANNEL>`	Channel name. If omitted, displays an interactive picker.

Supported channels: telegram, discord, slack, whatsapp, email, signal, matrix.

Each wizard:

Displays step-by-step instructions for obtaining credentials.
Prompts for tokens/credentials.
Saves tokens to ~/.librefang/.env with owner-only permissions.
Appends the channel configuration block to config.toml (prompts for confirmation).
Warns to restart the daemon if one is running.

Example:

# Interactive picker
librefang channel setup

# Direct setup
librefang channel setup telegram
librefang channel setup discord
librefang channel setup slack

librefang channel test

Send a test message through a configured channel.

librefang channel test <CHANNEL>

Arguments:

Argument	Description
`<CHANNEL>`	Channel name to test.

Requires a running daemon. Sends POST /api/channels/<channel>/test.

Example:

librefang channel test telegram

librefang channel enable

Enable a channel integration.

librefang channel enable <CHANNEL>

Arguments:

Argument	Description
`<CHANNEL>`	Channel name to enable.

In daemon mode: sends POST /api/channels/<channel>/enable. Without a daemon: prints a note that the change will take effect on next start.

librefang channel disable

Disable a channel without removing its configuration.

librefang channel disable <CHANNEL>

Arguments:

Argument	Description
`<CHANNEL>`	Channel name to disable.

In daemon mode: sends POST /api/channels/<channel>/disable. Without a daemon: prints a note to edit config.toml.

Config Commands

librefang config show

Display the current configuration file.

librefang config show

Prints the contents of ~/.librefang/config.toml with the file path as a header comment.

librefang config edit

Open the configuration file in your editor.

librefang config edit

Uses $EDITOR, then $VISUAL, then falls back to notepad (Windows) or vi (Unix).

librefang config get

Get a single configuration value by dotted key path.

librefang config get <KEY>

Arguments:

Argument	Description
`<KEY>`	Dotted key path into the TOML structure.

Example:

librefang config get default_model.provider
# groq

librefang config get api_listen
# 127.0.0.1:4545

librefang config get memory.decay_rate
# 0.05

librefang config set

Set a configuration value by dotted key path.

librefang config set <KEY> <VALUE>

Arguments:

Argument	Description
`<KEY>`	Dotted key path.
`<VALUE>`	New value. Type is inferred from the existing value (integer, float, boolean, or string).

Warning: This command re-serializes the TOML file, which strips all comments.

Example:

librefang config set default_model.provider anthropic
librefang config set default_model.model claude-sonnet-4-20250514
librefang config set api_listen "0.0.0.0:4545"

librefang config set-key

Save an LLM provider API key to ~/.librefang/.env.

librefang config set-key <PROVIDER>

Arguments:

Argument	Description
`<PROVIDER>`	Provider name (e.g. `groq`, `anthropic`, `openai`, `gemini`, `deepseek`, `openrouter`, `together`, `mistral`, `fireworks`, `perplexity`, `cohere`, `xai`, `brave`, `tavily`).

Behavior:

Prompts interactively for the API key.
Saves to ~/.librefang/.env as <PROVIDER_NAME>_API_KEY=<value>.
Runs a live validation test against the provider's API.
File permissions are restricted to owner-only on Unix.

Example:

librefang config set-key groq
# Paste your groq API key: gsk_...
# [ok] Saved GROQ_API_KEY to ~/.librefang/.env
# Testing key... OK

librefang config delete-key

Remove an API key from ~/.librefang/.env.

librefang config delete-key <PROVIDER>

Arguments:

Argument	Description
`<PROVIDER>`	Provider name.

Example:

librefang config delete-key openai

librefang config unset

Remove a configuration key from config.toml (distinct from delete-key which removes a provider API key from .env).

librefang config unset <KEY>

Arguments:

Argument	Description
`<KEY>`	Dotted config path to remove (e.g. `api.cors_origin`, `triggers.cooldown_secs`).

Example:

librefang config unset api.cors_origin

Note: unset rewrites the TOML file and strips comments. If you maintain hand-curated comments in config.toml, edit it manually instead.

librefang config test-key

Test provider connectivity with the stored API key.

librefang config test-key <PROVIDER>

Arguments:

Argument	Description
`<PROVIDER>`	Provider name.

Behavior:

Reads the API key from the environment (loaded from ~/.librefang/.env).
Hits the provider's models/health endpoint.
Reports OK (key accepted) or FAILED (401/403) (key rejected).
Exits with code 1 on failure.

Example:

librefang config test-key groq
# Testing groq (GROQ_API_KEY)... OK

Service Commands

Manage the system boot service so LibreFang starts automatically on login or reboot.

librefang service install

librefang service install

Behavior:

Linux: Creates a systemd user service at ~/.config/systemd/user/librefang.service, then runs systemctl --user daemon-reload and systemctl --user enable librefang.service.
macOS: Creates a LaunchAgent at ~/Library/LaunchAgents/ai.librefang.daemon.plist and loads it with launchctl load.
Windows: Adds a LibreFang entry to HKCU\Software\Microsoft\Windows\CurrentVersion\Run.

The binary path is detected from the running executable (std::env::current_exe). If you move the binary, re-run librefang service install to update the path.

Example:

librefang service install
# ✓ Wrote /home/user/.config/systemd/user/librefang.service
# ✓ Service enabled (will start on next login)

For headless Linux servers (no graphical login session), also enable lingering so the user service starts at boot:

loginctl enable-linger

librefang service uninstall

Remove the previously installed auto-start service.

librefang service uninstall

Behavior:

Linux: Disables and removes the systemd user service, then reloads the daemon.
macOS: Unloads and removes the LaunchAgent plist.
Windows: Deletes the registry Run entry.

Example:

librefang service uninstall
# ✓ Removed systemd user service

librefang service status

Check whether the auto-start service is registered and running.

librefang service status

Example:

librefang service status
# ✓ Systemd user service is registered
#   Enabled: enabled
#   Active: active

Slash Commands in Chat

The interactive chat (librefang chat, librefang agent chat, and the TUI chat panel) accepts slash commands. All commands are sourced from a single registry shared with channel adapters (Telegram, Slack, etc.) and the dashboard, so a command name means the same thing on every surface.

Type /help inside a chat session to render the list scoped to the CLI:

/model [name] — Show or switch agent model
/status       — Show system status
/help         — Show this help
/clear        — Clear chat history
/kill         — Kill the current agent and quit
/exit         — End chat session

Command	Description
`/model [name]`	Show the current model, or switch to `<name>` (provider-prefixed, e.g. `groq/llama-3.3-70b-versatile`).
`/status`	Print connection and agent status.
`/help`	Print the CLI command list.
`/clear`	Clear the visible chat history without resetting the session.
`/kill`	Terminate the current agent and exit chat.
`/exit`	End the chat session. `quit` is accepted as an alias.

Commands surfaced by channel adapters (/agents, /new, /usage, /triggers, /budget, …) are described under Provider Management — Channel Commands. Note that /new forks into a fresh session rather than wiping the current one — the previous session stays accessible from the channel and can be resumed. Unknown command names fall through to a single "unknown command" error rather than being passed to the model.

Top-Level Command Reference

Beyond the agent / hand / skill / workflow / channel / config groups documented above, these top-level commands ship with the CLI. All of them are real (verified against crates/librefang-cli/src/main.rs); some are aliases of nested forms.

Daemon lifecycle

Command	Purpose	Notable flags
`librefang start`	Start the daemon.	`--foreground` (no fork), `--log-file <path>`
`librefang stop`	Stop the running daemon.	—
`librefang restart`	Restart the daemon.	`--tail` (follow new logs), `--foreground`
`librefang health`	Quick readiness probe.	`--json`
`librefang status`	Show kernel + provider state.	`--watch <secs>` (refresh loop)
`librefang logs`	Tail daemon logs.	`--lines <n>`, `--follow` / `-f`
`librefang tui`	Launch the interactive terminal dashboard.	—

Setup / onboarding / migration

Command	Purpose	Notes
`librefang onboard`	Interactive setup wizard.	`--quick`, `--upgrade`
`librefang setup`	Non-interactive `init --quick` alias.	`--quick`, `--upgrade`
`librefang configure`	Interactive credential & channel wizard.	—
`librefang migrate --from <framework>`	Import config / sessions from another framework.	`<framework>` ∈ `openclaw`, `langchain`, `autogpt`, `openfang`
`librefang reset --confirm`	Wipe local config and state (destructive).	Requires `--confirm`
`librefang uninstall`	Remove LibreFang.	`--confirm`, `--keep-config`

Catalog & registry

Command	Purpose	Subcommands
`librefang models`	LLM model catalog.	`list`, `aliases`, `providers`, `set`
`librefang mcp`	MCP server management.	`list`, `catalog`, `add`, `remove`
`librefang webhooks`	Outbound webhook management.	`list`, `create`, `test`, `delete`
`librefang sessions [agent]`	List conversation sessions.	`--json`
`librefang memory`	Agent memory KV store.	`list`, `get`, `set`, `delete`
`librefang cron`	Scheduled job management.	`list`, `create`, `delete`, `enable`, `disable`
`librefang approvals`	Execution approval queue.	`list`, `approve`, `reject`

Security / auth / vault

Command	Purpose	Subcommands
`librefang vault`	Encrypted credential store.	`init`, `set`, `list`, `remove`
`librefang auth chatgpt`	Authenticate with ChatGPT (browser OAuth).	`--device-auth`
`librefang security`	Security audit and verification.	`status`, `audit`, `verify`
`librefang devices`	Device pairing management.	`list`, `pair`, `remove`
`librefang qr`	Render a pairing QR code on stdout.	—
`librefang hash-password`	Generate an Argon2id hash for `dashboard_pass_hash`.	`--password <plain>` (else prompts)

Agent shortcuts (aliases of nested forms)

Command	Same as	Purpose
`librefang spawn <template>`	`agent spawn`	Spawn an agent from template/manifest. `--name`, `--dry-run`
`librefang agents`	`agent list`	List agents. `--json`
`librefang kill <agent_id>`	`agent kill`	Kill a running agent.
`librefang message <agent> <text>`	—	Send one-shot message; print the reply. `--json`

Scaffolding

Command	Purpose
`librefang new skill`	Scaffold a new skill (interactive).
`librefang new mcp`	Scaffold a new MCP server.

`librefang hand` extra subcommands

The hand group already has list / install / activate / info / check-deps / install-deps / pause / resume / deactivate documented above. These are the additional ones:

Subcommand	Purpose
`hand status [id]`	Show hand status (single or all).
`hand active`	List active hand instances.
`hand settings <name>`	Show a hand's current configuration.
`hand set <name> <key> <value>`	Set a single hand-config value.
`hand reload`	Reload all `HAND.toml` files from disk.
`hand chat <name>`	Interactive chat with an active hand.

System & meta

Command	Purpose
`librefang system info`	Print platform / version / dependency info.
`librefang system version`	Print just the version string.
`librefang gateway`	Low-level daemon control (start / stop / restart / status), used by service supervisors that want to bypass the friendly `start` wrapper.

Slash commands not surfaced above

These slash commands exist in the registry alongside /help / /clear / etc. but were not previously documented:

Command	Behaviour
`/reboot`	Restart the agent process (resets in-process state, but keeps session history).
`/compact`	Trigger an LLM-based compaction round on the current session.
`/think`	Toggle visible chain-of-thought / reasoning rendering for the next reply.

CLI Command Reference

librefang agent new

librefang agent spawn

librefang agent list

librefang agent chat

librefang agent kill

librefang hand list

librefang hand active

librefang hand activate <name>

librefang hand deactivate <name>

librefang hand status [name]

librefang hand install <path>

librefang hand info <name>

librefang hand check-deps <name>

librefang hand install-deps <name>

librefang hand pause <name>

librefang hand resume <name>

librefang workflow list

librefang workflow create

librefang workflow run

librefang trigger list

librefang trigger create

librefang trigger get

librefang trigger update

librefang trigger enable / disable

librefang trigger delete

librefang skill list

librefang skill install

librefang skill remove

librefang skill search

librefang skill create

librefang channel list

librefang channel setup

librefang channel test

librefang channel enable

librefang channel disable

librefang config show

librefang config edit

librefang config get

librefang config set

librefang config set-key

librefang config delete-key

librefang config unset

librefang config test-key

librefang service install

librefang service uninstall

librefang service status

Daemon lifecycle

Setup / onboarding / migration

Catalog & registry

Security / auth / vault

Agent shortcuts (aliases of nested forms)

Scaffolding

librefang hand extra subcommands

System & meta

Slash commands not surfaced above

`librefang hand` extra subcommands