# OpenFang CLI Reference

Complete command-line reference for `openfang`, the CLI tool for the OpenFang Agent OS.

## Overview

The `openfang` binary is the primary interface for managing the OpenFang Agent OS. It supports two modes of operation:

- **Daemon mode** -- When a daemon is running (`openfang start`), CLI commands communicate with it over HTTP. This is the recommended mode for production use.
- **In-process mode** -- When no daemon is detected, commands that support it will boot an ephemeral in-process kernel. Agents spawned in this mode are not persisted and will be lost when the process exits.

Running `openfang` with no subcommand launches the interactive TUI (terminal user interface) built with ratatui, which provides a full dashboard experience in the terminal.

## Installation

### From source (cargo)

```bash
cargo install --path crates/openfang-cli
```

### Build from workspace

```bash
cargo build --release -p openfang-cli
# Binary: target/release/openfang (or openfang.exe on Windows)
```

### Docker

```bash
docker run -it openfang/openfang:latest
```

### Shell installer

```bash
curl -fsSL https://get.openfang.ai | sh
```

## Global Options

These options apply to all commands.

| Option | Description |
| --- | --- |
| `--config <PATH>` | Path to a custom config file. Overrides the default `~/.openfang/config.toml`. |
| `--help` | Print help information for any command or subcommand. |
| `--version` | Print the version of the `openfang` binary. |

**Environment variables:**

| Variable | Description |
| --- | --- |
| `RUST_LOG` | Controls log verbosity (e.g. `info`, `debug`, `openfang_kernel=trace`). |
| `OPENFANG_AGENTS_DIR` | Override the agent templates directory. |
| `EDITOR` / `VISUAL` | Editor used by `openfang config edit`. Falls back to `notepad` (Windows) or `vi` (Unix). |

## Command Reference

### openfang (no subcommand)

Launch the interactive TUI dashboard.

`openfang [--config <PATH>]`

### openfang init

Initialize the OpenFang workspace. Creates `~/.openfang/` with subdirectories (`data/`, `agents/`) and a default `config.toml`.

```bash
openfang init [--quick]
```

**Options:**

| Option | Description |
| --- | --- |
| `--quick` | Skip interactive prompts. Auto-detects the best available LLM provider and writes config immediately. Suitable for CI/scripts. |

**Example:**

```bash
# Interactive setup
openfang init

# Non-interactive (CI/scripts)
export GROQ_API_KEY="gsk_..."
openfang init --quick
```

### openfang start

Start the OpenFang daemon (kernel + API server).

```bash
openfang start [--config <PATH>]
```

### openfang status

Show the current kernel/daemon status.

```bash
openfang status [--json]
```

### openfang doctor

Run diagnostic checks on the OpenFang installation.

```bash
openfang doctor [--json] [--repair]
```

### openfang dashboard

Open the web dashboard in the default browser.

```bash
openfang dashboard
```

### openfang completion

Generate shell completion scripts.

```bash
openfang completion <SHELL>
```

## Agent Commands

### openfang agent new

Spawn an agent from a built-in template.

```bash
openfang agent new [<TEMPLATE>]
```

### openfang agent spawn

Spawn an agent from a custom manifest file.

```bash
openfang agent spawn <MANIFEST>
```

### openfang agent list

List all running agents.

```bash
openfang agent list [--json]
```

### openfang agent chat

Start an interactive chat session with a specific agent.

```bash
openfang agent chat <AGENT_ID>
```

### openfang agent kill

Terminate a running agent.

```bash
openfang agent kill <AGENT_ID>
```

## Workflow Commands

### openfang workflow list

List all registered workflows.

```bash
openfang workflow list
```

### openfang workflow create

Create a workflow from a JSON definition file.

```bash
openfang workflow create <FILE>
```

### openfang workflow run

Execute a workflow by ID.

```bash
openfang workflow run <WORKFLOW_ID> <INPUT>
```

## Trigger Commands

### openfang trigger list

List all event triggers.

```bash
openfang trigger list [--agent-id <ID>]
```

### openfang trigger create

Create an event trigger for an agent.

```bash
openfang trigger create <AGENT_ID> <PATTERN_JSON> [--prompt <TEMPLATE>] [--max-fires <N>]
```

### openfang trigger delete

Delete a trigger by ID.

```bash
openfang trigger delete <TRIGGER_ID>
```

## Skill Commands

### openfang skill list

List all installed skills.

```bash
openfang skill list
```

### openfang skill install

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

```bash
openfang skill install <SOURCE>
```

### openfang skill remove

Remove an installed skill.

```bash
openfang skill remove <NAME>
```

### openfang skill search

Search the FangHub marketplace for skills.

```bash
openfang skill search <QUERY>
```

### openfang skill create

Interactively scaffold a new skill project.

```bash
openfang skill create
```

## Channel Commands

### openfang channel list

List configured channels and their status.

```bash
openfang channel list
```

### openfang channel setup

Interactive setup wizard for a channel integration.

```bash
openfang channel setup [<CHANNEL>]
```

### openfang channel test

Send a test message through a configured channel.

```bash
openfang channel test <CHANNEL>
```

### openfang channel enable

Enable a channel integration.

```bash
openfang channel enable <CHANNEL>
```

### openfang channel disable

Disable a channel without removing its configuration.

```bash
openfang channel disable <CHANNEL>
```

## Config Commands

### openfang config show

Display the current configuration file.

```bash
openfang config show
```

### openfang config edit

Open the configuration file in your editor.

```bash
openfang config edit
```

### openfang config get

Get a single configuration value by dotted key path.

```bash
openfang config get <KEY>
```

### openfang config set

Set a configuration value by dotted key path.

```bash
openfang config set <KEY> <VALUE>
```

### openfang config set-key

Save an LLM provider API key to `~/.openfang/.env`.

```bash
openfang config set-key <PROVIDER>
```

### openfang config delete-key

Remove an API key from `~/.openfang/.env`.

```bash
openfang config delete-key <PROVIDER>
```

### openfang config test-key

Test provider connectivity with the stored API key.

```bash
openfang config test-key <PROVIDER>
```

## Quick Chat

### openfang chat

Quick alias for starting a chat session.

```bash
openfang chat [<AGENT>]
```

## Migration

### openfang migrate

Migrate configuration and agents from another agent framework.

```bash
openfang migrate --from <FRAMEWORK> [--source-dir <PATH>] [--dry-run]
```

## MCP Server

### openfang mcp

Start an MCP (Model Context Protocol) server over stdio.

```bash
openfang mcp
```

## Daemon Auto-Detect

The CLI uses a two-step mechanism to detect a running daemon:

1. **Read `daemon.json`:** On startup, the daemon writes `~/.openfang/daemon.json` containing the listen address. The CLI reads this file to learn where the daemon is.
2. **Health check:** The CLI sends `GET http://<listen_addr>/api/health` with a timeout.

## Environment File

OpenFang loads `~/.openfang/.env` into the process environment on every CLI invocation.

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | General error (invalid arguments, failed operations). |
| `130` | Interrupted by second `Ctrl+C`. |

## Examples

### First-time setup

```bash
# 1. Set your API key
export GROQ_API_KEY="gsk_your_key_here"

# 2. Initialize OpenFang
openfang init --quick

# 3. Start the daemon
openfang start
```

### Daily usage

```bash
# Quick chat (auto-spawns agent if needed)
openfang chat

# Check what's running
openfang status
```

### Agent management

```bash
# List running agents
openfang agent list
```

### Workflow automation

```bash
# Create a workflow
openfang workflow create ./review-pipeline.json
```

### Event triggers

```bash
# Create a trigger that fires on agent spawn
openfang trigger create <AGENT_ID> '{