# CLI Reference > Command-line interface for ForbocAI SDK v0.3.1 # 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: ```bash npm install -g forbocai@latest # or use npx npx forbocai ``` *** ## 🛠 System Commands ### `forbocai version` Display the current SDK version. ```bash $ npx forbocai version ForbocAI SDK v0.3.1 ``` ### `forbocai doctor` Diagnose system issues, check API connectivity, and verify configuration. ```bash $ 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 ` Set a persistent configuration value (saved to `~/.forbocai.json`). ```bash $ npx forbocai config set apiUrl http://localhost:3001 > Set apiUrl = http://localhost:3001 ``` ### `forbocai config get ` Get a specific configuration value. ```bash $ npx forbocai config get apiUrl http://localhost:3001 ``` ### `forbocai config list` List all configuration values. ```bash $ 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. ```bash $ 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. ```bash $ 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. ```bash $ 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. ```bash $ 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. ```bash $ 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 ` Start an interactive chat REPL with the agent. ```bash $ 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 ` View an agent's current state (mood, inventory, skills, relationships). ```bash $ 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 ` One-shot process input (non-interactive). ```bash $ 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 [--mood ] [--inventory ]` Manually update an agent's state. ```bash $ 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 ` Delete an agent permanently. ```bash $ npx forbocai agent delete ag_mock_1 > Deleting Agent: ag_mock_1... > Agent deleted: ag_mock_1 ``` *** ## 🧠 Memory Commands ### `forbocai memory list ` List all memories for an agent. ```bash $ 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 ` Perform a semantic search through the agent's memory bank. ```bash $ 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 ` Manually inject a memory/observation. ```bash $ npx forbocai memory store ag_mock_1 "The king is actually a doppelganger" > Storing memory... > Memory stored! > ID: mem_xyz789 ``` ### `forbocai memory clear ` Clear all memories for an agent (with confirmation). ```bash $ 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 ` Export all memories to a JSON file. ```bash $ 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 ` Validate an action JSON file against the game's neuro-symbolic rules. ```bash $ npx forbocai bridge validate action.json > Validating action from: action.json... > ✓ Action is VALID ``` Example `action.json`: ```json { "type": "ATTACK", "target": "orc_1", "payload": {} } ``` ### `forbocai bridge rules` List all active validation rules. ```bash $ 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 ` Export an agent's Soul to IPFS. ```bash $ npx forbocai soul export ag_mock_1 > Exporting Soul for Agent: ag_mock_1... > Soul Exported! > CID: QmXyzAbc123... > IPFS: ipfs://QmXyzAbc123... ``` ### `forbocai soul import ` Import an agent from an IPFS Soul. ```bash $ 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 ` Wake a Soul from cryo and start a chat session. ```bash $ 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. ```bash $ npx forbocai soul list > Listing exported Souls... Exported Souls: (Soul listing requires local storage or API endpoint) Use 'soul export ' to create a new Soul ``` ### `forbocai soul verify ` Verify a Soul's signature and integrity. ```bash $ 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`. ```bash $ 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 ` Check session progress. ```bash $ npx forbocai ghost status sess_ghost_1 > Checking Ghost session: sess_ghost_1... > Status: RUNNING > Progress: 45% > Duration: 120s > Errors: 0 ``` ### `forbocai ghost results ` Get detailed test results and metrics. ```bash $ 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 ` Stop a running Ghost session. ```bash $ 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. ```bash $ npx forbocai ghost history > Fetching Ghost session history... Recent Sessions: (Session history requires persistent storage) Use 'ghost run ' to start a new session ``` *** ## 🌍 Environment Variables | Variable | Description | Default | | ---------------- | -------------------- | ----------------------------------- | | `FORBOC_API_URL` | Override the API URL | `https://forbocai-api.onrender.com` | *** ## 📋 Quick Reference ```bash # System forbocai version forbocai doctor # Config forbocai config set forbocai config get 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 forbocai agent state forbocai agent process forbocai agent update --mood [--inventory ] forbocai agent delete # Memory forbocai memory list forbocai memory recall forbocai memory store forbocai memory clear forbocai memory export # Bridge forbocai bridge validate forbocai bridge rules # Soul forbocai soul export forbocai soul import forbocai soul chat forbocai soul list forbocai soul verify # Ghost forbocai ghost run [suite] forbocai ghost status forbocai ghost results forbocai ghost stop 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̷.*