CLI Reference (v0.3.1)

CLI_Réference // Cómmand_Líne

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

The ForbocAI SDK includes a powerful command-line interface for managing the entire Neuro-Symbolic Grid.

T̷h̵e̸ ̷t̵e̸r̷m̸i̵n̵a̶l̷ ̸i̷s̸ ̷y̴o̵u̷r̴ ̸p̵o̴r̵t̸a̵l̷.

Installation

The CLI is included with the SDK:

$ npm install -g forbocai@latest
$ # or use npx
$ npx forbocai <command>

🛠 System Commands

`forbocai version`

Display the current SDK version.

$ $ npx forbocai version
$ ForbocAI SDK v0.3.1

`forbocai doctor`

Diagnose system issues, check API connectivity, and verify configuration.

$ $ npx forbocai doctor
$ 
$ ╔════════════════════════════════════════╗
$ ║  ForbocAI Doctor                       ║
$ ╚════════════════════════════════════════╝
$ 
$ Checking system...
$ 
$ ✓ Node.js: v20.10.0
$ ✓ API URL: https://forbocai-api.onrender.com
$ ○ Config: Not configured (using defaults)
$ 
$ Testing API connection...
$ ✓ API: Online
$ 
$ Diagnosis complete.

⚙️ Config Commands

`forbocai config set <key> <value>`

Set a persistent configuration value (saved to ~/.forbocai.json).

$ $ npx forbocai config set apiUrl http://localhost:3001
$ > Set apiUrl = http://localhost:3001

`forbocai config get <key>`

Get a specific configuration value.

$ $ npx forbocai config get apiUrl
$ http://localhost:3001

`forbocai config list`

List all configuration values.

$ $ npx forbocai config list
$ 
$ Configuration (~/.forbocai.json):
$ 
$   apiUrl: http://localhost:3001
$ 
$ Defaults:
$   apiUrl: https://forbocai-api.onrender.com

🌐 API Commands

`forbocai api status`

Check API connection status.

$ $ npx forbocai api status
$ > Connecting to Neuro-Symbolic Grid...
$ > API: https://forbocai-api.onrender.com
$ > Status: ONLINE
$ > Message: Neuro-Symbolic Grid: ACTIVE
$ > Version: 1.0.0

🔮 Cortex Commands

`forbocai cortex models`

List available SLM models for local inference.

$ $ npx forbocai cortex models
$ > Fetching available models...
$ 
$   Available Models:
$ 
$   smollm2-135m
$     Name: SmolLM2 135M
$     Parameters: 135M
$     Size: 100MB
$     Capabilities: dialogue, structured_output
$ 
$   llama3-8b
$     Name: Llama 3 8B
$     Parameters: 8000M
$     Size: 4.5GB
$     Capabilities: dialogue, structured_output, reasoning

`forbocai cortex init [model]`

Initialize a local Small Language Model (SLM) instance.

$ $ npx forbocai cortex init smollm2-135m
$ > Initializing Cortex with model: smollm2-135m...
$ > Cortex Initialized!
$ > Instance ID: ctx_mock_123
$ > Model: smollm2-135m
$ > Status: ready

🤖 Agent Commands

`forbocai agent create [persona]`

Create a new AI agent with a persona.

$ $ npx forbocai agent create "A wise wizard who speaks in riddles"
$ > Creating Agent with persona: "A wise wizard who speaks in riddles"...
$ > Agent Created: ag_mock_1
$ > Mood: neutral

`forbocai agent list`

List all active agents.

$ $ npx forbocai agent list
$ > Listing agents...
$ > Found 2 agents:
$ 
$   1. ag_mock_1
$      Persona: A wise wizard who speaks in riddles...
$      Mood: neutral
$ 
$   2. ag_mock_2
$      Persona: A suspicious merchant...
$      Mood: suspicious

`forbocai agent chat <agentId>`

Start an interactive chat REPL with the agent.

$ $ npx forbocai agent chat ag_mock_1
$ 
$ ╔════════════════════════════════════════╗
$ ║  ForbocAI Agent Chat                   ║
$ ║  Agent: ag_mock_1                      ║
$ ║  Type 'exit' to quit                   ║
$ ╚════════════════════════════════════════╝
$ 
$ > You: Hello wizard!
$ > Agent: Greetings, traveler. The stars whisper of your arrival...
$ 
$ > You: exit
$ > Disconnecting from agent...

`forbocai agent state <agentId>`

View an agent’s current state (mood, inventory, skills, relationships).

$ $ npx forbocai agent state ag_mock_1
$ > Fetching state for Agent: ag_mock_1...
$ 
$   Agent State:
$ 
$   Mood: suspicious
$   Inventory: sword, potion, map
$   Skills:
$     stealth: 5
$     barter: 8
$   Relationships:
$     player: +15
$     guard: -5

`forbocai agent process <agentId> <input>`

One-shot process input (non-interactive).

$ $ npx forbocai agent process ag_mock_1 "What do you know about the dungeon?"
$ You seek the depths? Few return from the shadows below...
$ Instruction: IDLE

`forbocai agent update <agentId> [--mood <mood>] [--inventory <items>]`

Manually update an agent’s state.

$ $ npx forbocai agent update ag_mock_1 --mood happy --inventory "gold,gem,key"
$ > Updating Agent: ag_mock_1...
$ > Agent updated!
$   mood: happy
$   inventory: gold,gem,key

`forbocai agent delete <agentId>`

Delete an agent permanently.

$ $ npx forbocai agent delete ag_mock_1
$ > Deleting Agent: ag_mock_1...
$ > Agent deleted: ag_mock_1

🧠 Memory Commands

`forbocai memory list <agentId>`

List all memories for an agent.

$ $ npx forbocai memory list ag_mock_1
$ > Listing memories for Agent: ag_mock_1...
$ 
$   Memories (3):
$ 
$   1. [█████     ] Met a warrior named Thorin at the tavern...
$   2. [████████  ] Discovered a hidden cave behind the waterfall...
$   3. [██        ] Ate a stale bread roll...

`forbocai memory recall <agentId> <query>`

Perform a semantic search through the agent’s memory bank.

$ $ npx forbocai memory recall ag_mock_1 "hidden places"
$ > Recalling memories for: "hidden places"...
$ 
$   Relevant Memories:
$ 
$   1. [Score: 0.89] Discovered a hidden cave behind the waterfall...
$   2. [Score: 0.45] Heard rumors of a secret dungeon...

`forbocai memory store <agentId> <text>`

Manually inject a memory/observation.

$ $ npx forbocai memory store ag_mock_1 "The king is actually a doppelganger"
$ > Storing memory...
$ > Memory stored!
$ > ID: mem_xyz789

`forbocai memory clear <agentId>`

Clear all memories for an agent (with confirmation).

$ $ npx forbocai memory clear ag_mock_1
$ > Clearing memories for Agent: ag_mock_1...
$ > This action cannot be undone!
$ Type "CONFIRM" to proceed: CONFIRM
$ > Memories cleared

`forbocai memory export <agentId>`

Export all memories to a JSON file.

$ $ npx forbocai memory export ag_mock_1
$ > Exporting memories for Agent: ag_mock_1...
$ > Memories exported to: memories_ag_mock_1_1738700000000.json

🛡 Bridge Commands

`forbocai bridge validate <file.json>`

Validate an action JSON file against the game’s neuro-symbolic rules.

$ $ npx forbocai bridge validate action.json
$ > Validating action from: action.json...
$ > ✓ Action is VALID

Example action.json:

1 {
2   "type": "ATTACK",
3   "target": "orc_1",
4   "payload": {}
5 }

`forbocai bridge rules`

List all active validation rules.

$ $ npx forbocai bridge rules
$ > Fetching validation rules...
$ 
$   Built-in Rules:
$ 
$   core.movement
$     Actions: MOVE, WALK, RUN
$     Validates: Coordinates, world bounds
$ 
$   core.attack
$     Actions: ATTACK, HIT, STRIKE
$     Validates: Target exists
$ 
$   core.interact
$     Actions: INTERACT, USE, PICKUP
$     Validates: Object specified
$ 
$   core.speak
$     Actions: SPEAK, SAY, SHOUT
$     Validates: Text not empty
$ 
$   core.resources
$     Actions: (all)
$     Validates: HP > 0, sufficient mana

💎 Soul Commands

`forbocai soul export <agentId>`

Export an agent’s Soul to IPFS.

$ $ npx forbocai soul export ag_mock_1
$ > Exporting Soul for Agent: ag_mock_1...
$ > Soul Exported!
$ > CID: QmXyzAbc123...
$ > IPFS: ipfs://QmXyzAbc123...

`forbocai soul import <cid>`

Import an agent from an IPFS Soul.

$ $ npx forbocai soul import QmXyzAbc123
$ > Importing Soul from CID: QmXyzAbc123...
$ > Soul Imported!
$ > New Agent ID: ag_imported_1
$ > Persona: A wise wizard who speaks in riddles

`forbocai soul chat <cid>`

Wake a Soul from cryo and start a chat session.

$ $ npx forbocai soul chat QmXyzAbc123
$ > Waking Soul from cryo: QmXyzAbc123...
$ > Soul awakened! Temporary Agent: ag_temp_1
$ > Persona: A wise wizard who speaks in riddles
$ 
$ ╔════════════════════════════════════════╗
$ ║  ForbocAI Agent Chat                   ║
$ ║  Agent: ag_temp_1                      ║
$ ║  Type 'exit' to quit                   ║
$ ╚════════════════════════════════════════╝
$ 
$ > You:

`forbocai soul list`

List all exported Souls.

$ $ npx forbocai soul list
$ > Listing exported Souls...
$ 
$   Exported Souls:
$ 
$   (Soul listing requires local storage or API endpoint)
$   Use 'soul export <agentId>' to create a new Soul

`forbocai soul verify <cid>`

Verify a Soul’s signature and integrity.

$ $ npx forbocai soul verify QmXyzAbc123
$ > Verifying Soul: QmXyzAbc123...
$ > Soul Verified!
$ > Name: Wizard of the North
$ > DNA: dna_sequence_xyz_encrypted...
$ > Signature: ✓ Valid

👻 Ghost Commands

`forbocai ghost run [suite]`

Start a QA test session. Available suites: exploration, combat, dialogue, pathfinding, full.

$ $ npx forbocai ghost run combat
$ > Starting Ghost QA session...
$ > Test Suite: combat
$ > Session Started!
$ > Session ID: sess_ghost_1
$ > Status: running
$ 
$ > To check status: forbocai ghost status sess_ghost_1
$ > To get results:  forbocai ghost results sess_ghost_1

`forbocai ghost status <sessionId>`

Check session progress.

$ $ npx forbocai ghost status sess_ghost_1
$ > Checking Ghost session: sess_ghost_1...
$ > Status: RUNNING
$ > Progress: 45%
$ > Duration: 120s
$ > Errors: 0

`forbocai ghost results <sessionId>`

Get detailed test results and metrics.

$ $ npx forbocai ghost results sess_ghost_1
$ > Fetching Ghost results: sess_ghost_1...
$ 
$ ╔════════════════════════════════════════╗
$ ║  Ghost QA Results                      ║
$ ╚════════════════════════════════════════╝
$ 
$   Total Tests: 5
$   Passed: 4
$   Failed: 1
$   Pass Rate: 80.0%
$   Duration: 1245ms
$   Coverage: 82.0%
$ 
$   Metrics:
$     avgFrameRate: 58.5
$     memoryUsageMB: 512.3
$     aiDecisionsPerSec: 15.2
$     explorationCoverage: 0.67
$ 
$   Tests:
$     ✓ test.navigation.basic (150ms)
$     ✓ test.combat.attack (230ms)
$     ✓ test.inventory.pickup (95ms)
$     ✗ test.dialogue.npc (450ms)
$       Error: Timeout waiting for NPC response
$     ✓ test.ai.pathfinding (320ms)

`forbocai ghost stop <sessionId>`

Stop a running Ghost session.

$ $ npx forbocai ghost stop sess_ghost_1
$ > Stopping Ghost session: sess_ghost_1...
$ > Session stop requested
$ > Status: Stopped

`forbocai ghost history`

List past Ghost sessions.

$ $ npx forbocai ghost history
$ > Fetching Ghost session history...
$ 
$   Recent Sessions:
$ 
$   (Session history requires persistent storage)
$   Use 'ghost run <suite>' to start a new session

🌍 Environment Variables

Variable	Description	Default
`FORBOC_API_URL`	Override the API URL	`https://forbocai-api.onrender.com`

📋 Quick Reference

$ # System
$ forbocai version
$ forbocai doctor
$ 
$ # Config
$ forbocai config set <key> <value>
$ forbocai config get <key>
$ forbocai config list
$ 
$ # API
$ forbocai api status
$ 
$ # Cortex
$ forbocai cortex models
$ forbocai cortex init [model]
$ 
$ # Agent
$ forbocai agent create [persona]
$ forbocai agent list
$ forbocai agent chat <id>
$ forbocai agent state <id>
$ forbocai agent process <id> <text>
$ forbocai agent update <id> --mood <mood> [--inventory <items>]
$ forbocai agent delete <id>
$ 
$ # Memory
$ forbocai memory list <agentId>
$ forbocai memory recall <agentId> <query>
$ forbocai memory store <agentId> <text>
$ forbocai memory clear <agentId>
$ forbocai memory export <agentId>
$ 
$ # Bridge
$ forbocai bridge validate <file.json>
$ forbocai bridge rules
$ 
$ # Soul
$ forbocai soul export <agentId>
$ forbocai soul import <cid>
$ forbocai soul chat <cid>
$ forbocai soul list
$ forbocai soul verify <cid>
$ 
$ # Ghost
$ forbocai ghost run [suite]
$ forbocai ghost status <id>
$ forbocai ghost results <id>
$ forbocai ghost stop <id>
$ forbocai ghost history

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

T̷h̵e̸ ̷G̶r̸i̵d̷ ̷i̶s̵ ̷n̴o̶w̴ ̷f̷u̶l̸l̸y̶ ̷o̶p̷e̵r̷a̸t̷i̶o̸n̸a̴l̷.