Getting Started

CLI Reference

Commands implemented by @forbocai/node

View as Markdown

CLI Reference (v0.6.3)

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

$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

$# 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.