CLI Reference

Complete command-line reference for the weft binary, covering all subcommands, flags, and examples.

The weft command-line interface provides tools for running agents, managing channels, sessions, memory, cron jobs, workspaces, skills, agents, MCP servers, security audits, and configuration.

Global Flags

These flags are available on all subcommands.

Flag	Description
`--verbose`, `-v`	Enable debug-level logging (default level is `warn`)
`--version`	Show version and exit
`--help`, `-h`	Show help text and exit

The RUST_LOG environment variable overrides both defaults if set (e.g., RUST_LOG=info weft agent).

Agent and Gateway

weft agent

Start an interactive agent REPL, or send a single message and exit.

weft agent [FLAGS] [OPTIONS]

Option	Description
`--message`, `-m` `<MSG>`	Send a single message and exit. Omit for interactive REPL.
`--model` `<MODEL>`	Override the model (e.g., `openai/gpt-4o`).
`--config`, `-c` `<PATH>`	Path to a config file.
`--intelligent-routing`	Enable vector-memory routing. Requires the feature to be compiled in.

weft agent                                         # interactive REPL
weft agent -m "Summarize today's open issues"      # single message
weft agent --model openai/gpt-4o -m "Draft update" # override model

weft gateway

Start the multi-channel gateway. Launches all enabled channels, the agent loop, and outbound dispatch. Runs in the foreground until SIGINT (Ctrl+C).

weft gateway [OPTIONS]

Option	Description
`--config`, `-c` `<PATH>`	Path to a config file.
`--intelligent-routing`	Enable vector-memory routing.

weft gateway
weft gateway -c /etc/weft/production.toml --intelligent-routing

weft status

Display system status summary (gateway, channels, agent health).

weft status [--detailed] [-c <PATH>]

Agents

weft agents list

List all agents with source annotation (NAME, SOURCE, MODEL, DESCRIPTION).

weft agents list

weft agents show

Show details of a specific agent.

weft agents show <NAME>

weft agents use

Set the active agent for the next session.

weft agents use <NAME>

Skills

weft skills list

List all skills with source annotation (NAME, SOURCE, FORMAT, DESCRIPTION).

weft skills list

weft skills show

Show details of a specific skill.

weft skills show <NAME>

weft skills install

Install a skill from a local path to ~/.clawft/skills/.

weft skills install <PATH>

weft skills remove

Remove a user-installed skill.

weft skills remove <NAME>

Channels

weft channels status

Display the status of all configured channels.

weft channels status [-c <PATH>]

Sessions

weft sessions list

List all sessions (session key, message count, last updated).

weft sessions list [-c <PATH>]

weft sessions inspect

Display the full message history for a session.

weft sessions inspect <SESSION_ID> [-c <PATH>]

weft sessions delete

Delete a session and its history.

weft sessions delete <SESSION_ID> [-c <PATH>]

Memory

weft memory show

Display the contents of MEMORY.md.

weft memory show [-c <PATH>]

weft memory history

Display the contents of HISTORY.md.

weft memory history [-c <PATH>]

weft memory search

Search memory and history for matching entries.

weft memory search <QUERY> [--limit <N>] [-c <PATH>]

weft memory export

Export memory data with a WITNESS integrity chain.

weft memory export [--output <PATH>] [-c <PATH>]

weft memory import

Import previously exported memory data. Validates the WITNESS chain before applying.

weft memory import <PATH> [-c <PATH>]

Cron Jobs

weft cron list

List all configured cron jobs.

weft cron list [-c <PATH>]

weft cron add

Add a new cron job.

weft cron add --name <NAME> --schedule <CRON_EXPR> --prompt <PROMPT> [-c <PATH>]

weft cron remove / enable / disable / run

weft cron remove <JOB_ID>    # remove a job
weft cron enable <JOB_ID>    # enable a disabled job
weft cron disable <JOB_ID>   # disable without removing
weft cron run <JOB_ID>       # manually trigger immediately

Workspaces

weft workspace create

weft workspace create <NAME> [--dir <PATH>]

weft workspace list

weft workspace list [--all]

weft workspace show / load / status / delete

weft workspace show <AGENT_ID>
weft workspace load <NAME_OR_PATH>
weft workspace status
weft workspace delete <NAME> [--yes]

weft workspace config

Manage workspace configuration using dot-separated keys.

weft workspace config set <KEY> <VALUE>
weft workspace config get <KEY>
weft workspace config reset

Example:

weft workspace config set agents.defaults.model openai/gpt-4o
weft workspace config get agents.defaults.model

Configuration

weft config show

Print the full resolved configuration as JSON.

weft config show [-c <PATH>]

weft config section

Print a specific section (agents, gateway, channels, tools).

weft config section <NAME> [-c <PATH>]

MCP

weft mcp-server

Start an MCP tool server over stdio. Exposes all registered tools as an MCP server for clients like Claude Desktop or Cursor.

weft mcp-server [-c <PATH>]

weft mcp add / remove / list

Manage dynamic MCP server connections.

weft mcp add <NAME> -- <COMMAND...>
weft mcp remove <NAME>
weft mcp list

Example:

weft mcp add github -- npx -y @modelcontextprotocol/server-github
weft mcp list
weft mcp remove github

Security

weft security scan

Run 57 security audit checks against the workspace and configuration.

weft security scan [--fix] [-c <PATH>]

Utilities

weft onboard

Set up initial configuration and workspace.

weft onboard [--yes] [--dir <PATH>]

weft completions

Generate shell completion scripts.

weft completions <SHELL>   # bash, zsh, fish, powershell

eval "$(weft completions bash)"                              # current session
weft completions zsh > ~/.zfunc/_weft                        # persist for zsh
weft completions fish > ~/.config/fish/completions/weft.fish # fish

weft help

Show help for a specific topic or general overview.

weft help [TOPIC]   # skills, agents, tools, commands, config

On this page