CLI Reference

Chibi uses a lowercase/UPPERCASE pattern: lowercase operates on current context, UPPERCASE operates on a specified context.

Context Operations

Flag	Description
`-c, --switch-context <NAME>`	Switch to a context (persistent); `new` for auto-name, `new:prefix` for prefixed, `-` for previous
`-C, --ephemeral-context <NAME>`	Use context for this invocation only (doesn't change global state)
`-l, --list-current-context`	Show current context info (name, prompt count, tasks, goals)
`-L, --list-contexts`	List all contexts (shows `[active]` or `[stale]` lock status)
`-d, --destroy-current-context`	Destroy the current context
`-D, --destroy-context <CTX>`	Destroy a specified context
`-a, --archive-current-history`	Archive current context history (saves to transcript)
`-A, --archive-history <CTX>`	Archive specified context's history
`-z, --compact-current-context`	Compact current context (LLM summarizes)
`-Z, --compact-context <CTX>`	Compact specified context (LLM summarizes)
`-r, --rename-current-context <NEW>`	Rename current context
`-R, --rename-context <OLD> <NEW>`	Rename specified context
`-b, --check-all-inboxes`	Check all context inboxes and process any messages
`-B, --check-inbox-for <CTX>`	Check inbox for specified context and process any messages

Previous Context Reference

The special context name - can be used to reference the previous context in any command that accepts a context name (-c, -C, -D, -A, -Z, -R, -G, -N, -Y, --clear-cache-for). The previous context is tracked in session.json and updated whenever you use -c to switch contexts.

Examples:

chibi -c dev          # Switch to 'dev', previous='default'
chibi -c production   # Switch to 'production', previous='dev'
chibi -c -            # Switch to 'dev', previous='production' (swaps!)
chibi -c -            # Switch to 'production', previous='dev' (swaps back!)

Swap Behavior (like cd -): When using -c - to switch contexts, the current and previous contexts swap places, just like the cd - command in bash. This allows you to toggle back and forth between two contexts repeatedly:

chibi -c work         # current='work', previous='personal'
chibi -c -            # current='personal', previous='work'
chibi -c -            # current='work', previous='personal'

Notes:

- is a reserved name and cannot be used as a literal context name
If no previous context exists (first invocation), you'll get an error: "No previous context available"
Only persistent switches (-c) update previous_context in session.json and use swap behavior
Ephemeral switches (-C -) resolve to previous context but don't swap or persist changes
Works with all context name parameters: -D - deletes previous context, -G - 10 shows previous context's log, etc.
Attached flag syntax works: both -xc- and -xc - are valid

Inspection & History

Flag	Description
`-g, --show-current-log <N>`	Show last N log entries from current context (negative = from start)
`-G, --show-log <CTX> <N>`	Show last N log entries from specified context
`-n, --inspect-current <THING>`	Inspect: `system_prompt`, `reflection`, `tasks` (or `todos`), `goals`, `home`, `list`, or config fields
`-N, --inspect <CTX> <THING>`	Inspect specified context

System Prompt

Flag	Description
`-y, --set-current-system-prompt <PROMPT>`	Set system prompt for current context (text or file path)
`-Y, --set-system-prompt <CTX> <PROMPT>`	Set system prompt for specified context

Username

Flag	Description
`-u, --set-username <NAME>`	Set username (persists to context's local.toml)
`-U, --ephemeral-username <NAME>`	Set username for this invocation only

Plugins & Tools

Flag	Description
`-p, --plugin <NAME> "ARGS"`	Run a plugin directly with shell-style args
`-P, --call-tool <TOOL> JSON`	Call a tool directly with JSON arguments

Cache Management

Flag	Description
`--clear-cache`	Clear the tool output cache for current context
`--clear-cache-for <CTX>`	Clear the tool output cache for specified context
`--cleanup-cache`	Remove old cache entries across all contexts

Model

Flag	Description
`-m, --set-model <MODEL>`	Set model for current context (persists to local.toml, validated live)
`-M, --set-model-for-context <CTX> <MODEL>`	Set model for specified context

Model names are validated live against the OpenRouter API before being written. An unknown model ID returns an error and no write occurs.

chibi -m anthropic/claude-sonnet-4          # Set model for current context
chibi -M research openai/o3                 # Set model for 'research' context
chibi -m anthropic/claude-sonnet-4 "Hello"  # Set model, then chat

Model Metadata

Flag	Description
`--model-metadata <MODEL>`	Show model metadata in TOML format (settable fields only)
`--model-metadata-full <MODEL>`	Show full model metadata (with pricing, capabilities, parameter ranges)

Model metadata is fetched via ratatoskr's gateway (embedded registry → cache → OpenRouter API on miss). --model-metadata shows only fields you can set under [models] in config.toml, while --model-metadata-full includes everything (pricing, capabilities, parameter ranges).

chibi --model-metadata anthropic/claude-sonnet-4       # Settable fields only
chibi --model-metadata-full openai/gpt-4o              # Full metadata including pricing

Control Flags

Flag	Description
`-v, --verbose`	Show extra info (tools loaded, warnings, etc.)
`-t, --trust`	Auto-approve all permission checks (for automation/headless)
`--show-thinking`	Display thinking/reasoning content from models that support extended thinking
`--hide-tool-calls`	Hide tool call display (tool calls are shown by default)
`--no-tool-calls`	Omit tools from API requests entirely (pure text mode)
`-x, --force-call-user`	Force return to user after operations (skip LLM)
`-X, --force-call-agent`	Force agent continuation (overrides implied -x)
`--raw`	Disable markdown rendering (plain text output)
`-s, --set <KEY=VALUE>`	Override a config value for this invocation (repeatable)
`-h, --help`	Show help message
`--version`	Show version

Programmatic / JSON Mode

JSON mode has moved to the separate chibi-json binary. The CLI is now text-only.

# programmatic usage (v0.8.0+)
chibi-json < input.json > output.jsonl
chibi-json --json-schema          # print input schema
chibi-json --version

chibi-json reads a JSON object from stdin, emits JSONL output, and always runs in trust mode (all permissions auto-approved). See chibi-json --json-schema for the full input format.

Input format:

{
  "command": { "send_prompt": { "prompt": "Hello" } },
  "context": { "switch": { "name": "coding" } },
  "flags": { "force_call_agent": true },
  "overrides": { "no_tool_calls": "true" }
}

Flags (ephemeral command modifiers): "force_call_user", "force_call_agent"

Config overrides (via "overrides" map or "config" object): "no_tool_calls", "fuel", "model", and other core config fields. Presentation fields (verbose, hide_tool_calls, show_thinking) are CLI-only and not available via chibi-json.

Simple commands: "list_contexts", "list_current_context", "no_op"

Commands with arguments:

{ "send_prompt": { "prompt": "..." } }
{ "destroy_context": { "name": "..." } } (name optional, null = current)
{ "archive_history": { "name": "..." } }
{ "compact_context": { "name": "..." } }
{ "rename_context": { "old": "...", "new": "..." } }
{ "show_log": { "context": "...", "count": 10 } }
{ "inspect": { "context": "...", "thing": "tasks" } }
{ "set_system_prompt": { "context": "...", "prompt": "..." } }
{ "set_model": { "context": "...", "model": "..." } } (context optional)
{ "run_plugin": { "name": "...", "args": [...] } }
{ "call_tool": { "name": "...", "args": [...] } }

Context selection: "current", { "switch": { "name": "..." } }, { "ephemeral": { "name": "..." } }

Username: { "persistent": "name" }, { "ephemeral": "name" }

Home/project root: set via "home" and "project_root" fields in the JSON input.

Directory Override

Flag	Description
`--home <PATH>`	Override chibi home directory (default: `~/.chibi`)
`--project-root <PATH>`	Override project root directory (default: cwd, or `CHIBI_PROJECT_ROOT` env)

The home directory is resolved in this order:

--home CLI flag (highest priority)
CHIBI_HOME environment variable
~/.chibi default

Use -n home to inspect the resolved path.

Debug Flags

Flag	Description
`--debug <KEY[,KEY,...]>`	Enable debug features (comma-separated, see below)
`--destroy-at <TIMESTAMP>`	Auto-destroy this context at a Unix timestamp
`--destroy-after-inactive <SECS>`	Auto-destroy this context after N seconds of inactivity

Debug Keys

Key	Description
`request-log`	Log full API request bodies to `requests.jsonl`
`response-meta`	Log response metadata/usage stats to `response_meta.jsonl`
`all`	Enable all logging features above
`md=<FILENAME>`	Render a markdown file and quit (implies `-x`, forces rendering even without TTY)
`force-markdown`	Force markdown rendering even when stdout is not a TTY

Debug Logging

Debug output is written to files in the context directory:

requests.jsonl - Full API request bodies (with request-log or all)
response_meta.jsonl - Response metadata, usage stats, model info (with response-meta or all)

Markdown Rendering

You can render a markdown file without invoking the LLM:

# Render a markdown file
chibi --debug md=README.md

# Works with any markdown file
chibi --debug md=docs/guide.md

This is useful for:

Previewing markdown files with terminal rendering
Testing markdown rendering without starting a conversation
Quick markdown file viewing

The md=<FILENAME> feature automatically:

Implies -x (no LLM invocation) and exits after rendering
Forces markdown rendering even when stdout is not a TTY (e.g., when piped or in CI)

Force Markdown Rendering

By default, markdown rendering only activates when stdout is a TTY (terminal). To force rendering even when piped or redirected:

# Force markdown rendering in a normal conversation
chibi --debug force-markdown "Tell me about Rust"

# Useful for piping formatted output
chibi --debug force-markdown "List the files" | less -R

Note: --debug md=<file> automatically forces rendering, so you don't need to combine them.

Combining Debug Keys

Multiple debug keys can be combined with commas:

# Enable request logging and force markdown rendering
chibi --debug request-log,force-markdown "Tell me about Rust"

# Log requests and response metadata
chibi --debug request-log,response-meta "Hello"

Auto-Destroy

Mark a context for automatic destruction using lifecycle flags:

# Destroy context after 60 seconds of inactivity
chibi --destroy-after-inactive 60 -c test-ctx

# Destroy context at a specific Unix timestamp
chibi --destroy-at 1234567890 -c test-ctx

Auto-destroy runs at the start of every chibi invocation and destroys all contexts that meet their configured criteria.

Flag Behavior

Implied -x (force-call-user)

These flags produce output or operate on other contexts, so they imply -x:

-l, -L, -d, -D, -A, -Z, -R, -g, -G, -n, -N, -Y, -M, -p, -P, --model-metadata, --model-metadata-full, --debug md=<file>

Combinable with Prompt

These flags can be combined with a prompt (execute operation, then invoke LLM):

-c, -C, -a, -z, -r, -m, -y, -u, -U, -v

Force Override

Use -X/--force-call-agent to override implied -x:

# Normally -L implies -x (skip LLM)
chibi -L

# Force agent continuation after listing
chibi -L -X "Now help me with something"

Prompt Input

Command Line

# Single argument (can contain spaces)
chibi What is Rust?

# Multiple words become one prompt
chibi Tell me about ownership in Rust

# Use -- to force prompt interpretation
chibi -- -v is not a flag here

Interactive

# Start interactive mode (end with . on empty line)
chibi
Enter your prompt:
- Line 1
- Line 2
.

Piped

# Pipe content as prompt
echo "What is 2+2?" | chibi

# Combine piped input with argument
cat file.txt | chibi "Summarize this"

Output Philosophy

stdout: Only LLM responses (clean, pipeable)
stderr: Diagnostics (only with -v)

# Pipe to another command
chibi "Generate JSON" | jq .

# Save to file
chibi "Write a poem" > poem.txt

# Use in scripts
result=$(chibi "What is 2+2? Just the number.")

Examples

Basic Usage

chibi What are the benefits of using Rust?

Context Management

chibi -c rust-learning          # Switch context
chibi -c new                    # Auto-named context
chibi -c new:bugfix             # Prefixed auto-name
chibi -L                        # List all contexts
chibi -l                        # Current context info

Custom Prompts

chibi -c coding
chibi -y "You are a senior engineer."
chibi -n system_prompt          # View it

Tool Debugging

chibi -v "Read my Cargo.toml"
# stderr: [Tool: file_head(path: Cargo.toml)]

Scripting

cat error.log | chibi "explain this"
git diff | chibi "review these changes"
chibi "List 5 numbers as JSON" | jq '.[0]'

Sub-Agents

# Run in another context without switching
chibi -C research "Find info about X"

# With custom system prompt
chibi -C coding -y "You are a reviewer" "Review this code"

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

Context Operations

Previous Context Reference

Inspection & History

System Prompt

Username

Plugins & Tools

Cache Management

Model

Model Metadata

Control Flags

Programmatic / JSON Mode

Directory Override

Debug Flags

Debug Keys

Debug Logging

Markdown Rendering

Force Markdown Rendering

Combining Debug Keys

Auto-Destroy

Flag Behavior

Implied -x (force-call-user)

Combinable with Prompt

Force Override

Prompt Input

Command Line

Interactive

Piped

Output Philosophy

Examples

Basic Usage

Context Management

Custom Prompts

Tool Debugging

Scripting

Sub-Agents

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

Context Operations

Previous Context Reference

Inspection & History

System Prompt

Username

Plugins & Tools

Cache Management

Model

Model Metadata

Control Flags

Programmatic / JSON Mode

Directory Override

Debug Flags

Debug Keys

Debug Logging

Markdown Rendering

Force Markdown Rendering

Combining Debug Keys

Auto-Destroy

Flag Behavior

Implied -x (force-call-user)

Combinable with Prompt

Force Override

Prompt Input

Command Line

Interactive

Piped

Output Philosophy

Examples

Basic Usage

Context Management

Custom Prompts

Tool Debugging

Scripting

Sub-Agents