***

title: CLI Reference
subtitle: Commands implemented by @forbocai/node
slug: npm/cli
-------------

# CLI Reference (v0.6.3)

The CLI binary is shipped by `@forbocai/node` as `forbocai`.

```bash
npx forbocai <command> [subcommand] [args]
```

## Top-Level Commands

* `version`
* `doctor`
* `status`
* `config set <key> <value>`
* `config get <key>`
* `config list`
* `cortex init [model]`
* `npc create|state|update|process|chat`
* `memory list|recall|store|clear|export`
* `bridge validate|rules|preset`
* `soul export|import|list|chat`
* `ghost run|status|results|stop|history`

## Config and Environment

CLI config file: `~/.forbocai.json`

Supported env vars:

* `FORBOCAI_API_URL`
* `FORBOCAI_API_KEY`

Resolution precedence is env var first, then config file.

## Common Commands

```bash
# health
npx forbocai doctor
npx forbocai status

# config
npx forbocai config set apiUrl https://api.forboc.ai
npx forbocai config set apiKey fb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npx forbocai config list

# cortex
npx forbocai cortex init smollm2-135m

# npc
npx forbocai npc create "A careful blacksmith"
npx forbocai npc process <npcId> "Can you repair this sword?"
npx forbocai npc chat <npcId>

# memory
npx forbocai memory list <npcId>
npx forbocai memory recall <npcId> "sword"
npx forbocai memory store <npcId> "Player repaired their blade"

# bridge
npx forbocai bridge rules
npx forbocai bridge validate ./action.json
npx forbocai bridge preset rpg

# soul
npx forbocai soul export <npcId>
npx forbocai soul import <txId-or-local-json>
npx forbocai soul list 20

# ghost
npx forbocai ghost run exploration
npx forbocai ghost status <sessionId>
npx forbocai ghost results <sessionId>
npx forbocai ghost history
```

## Notes

* `memory clear <npcId>` prompts for confirmation before API-side deletion.
* `npc process` and `npc chat` require API connectivity and a configured key when the target API enforces auth.
* `npc state` operates on the currently active in-memory NPC state in the CLI process.