> ## Documentation Index > Fetch the complete documentation index at: https://docs.shannon.run/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Complete reference for the Shannon CLI - submit tasks, stream events, manage sessions, schedules, and more from the terminal ## Installation ```bash theme={"dark"} pip install shannon-sdk ``` This installs the `shannon` CLI command. Verify with: ```bash theme={"dark"} shannon --help ``` From source (development): ```bash theme={"dark"} git clone https://github.com/Kocoro-lab/Shannon.git cd Shannon/clients/python pip install -e . ``` ## Connection ### Local (self-hosted) ```bash theme={"dark"} shannon --base-url http://localhost:8080 submit "Hello world" --wait ``` ### Shannon Cloud Register at [https://shannon.run](https://shannon.run) to get an API key, then: ```bash theme={"dark"} shannon --base-url http://localhost:8080 --api-key YOUR_API_KEY \ submit "Hello world" --wait ``` ### Environment Variables Set these to avoid passing flags on every call: ```bash theme={"dark"} export SHANNON_BASE_URL=http://localhost:8080 export SHANNON_API_KEY=sk_your_key_here # export SHANNON_BEARER_TOKEN=eyJ... # alternative to API key ``` Then simply: ```bash theme={"dark"} shannon submit "Hello world" --wait ``` | Variable | Default | Description | | ---------------------- | ----------------------- | ------------------------------------------ | | `SHANNON_BASE_URL` | `http://localhost:8080` | Gateway URL | | `SHANNON_API_KEY` | (none) | API key auth (sent as `X-API-Key` header) | | `SHANNON_BEARER_TOKEN` | (none) | Bearer token auth (alternative to API key) | ## Global Options These go before the command name: ```bash theme={"dark"} shannon [--base-url URL] [--api-key KEY] [--bearer-token TOKEN] COMMAND [OPTIONS] ``` *** ## Tasks ### submit - Submit a task ```bash theme={"dark"} shannon submit QUERY [OPTIONS] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | --------------------- | | `QUERY` | Yes | The task query string | **Options:** | Flag | Type | Description | | ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--wait` | flag | Block until task completes, print result | | `--session-id` | string | Attach task to a session | | `--mode` | `simple` \| `standard` \| `complex` \| `supervisor` | Execution mode hint | | `--model-tier` | `small` \| `medium` \| `large` | Model tier selection | | `--model-override` | string | Specific model (e.g. `gpt-5-nano-2025-08-07`) | | `--provider-override` | string | Force provider: `openai`, `anthropic`, `google`, `groq`, `xai`, `deepseek`, `qwen`, `zai`, `ollama`, `mistral`, `cohere` | | `--force-research` | flag | Force ResearchWorkflow with citations | | `--research-strategy` | `quick` \| `standard` \| `deep` \| `academic` | Research strategy preset | | `--max-iterations` | int (1-50) | Override max research iterations | | `--max-concurrent-agents` | int (1-20) | Override max concurrent agents | | `--enable-verification` | flag | Enable claim verification | | `--disable-verification` | flag | Disable claim verification | | `--enable-citations` | flag | Enable citation collection | | `--disable-citations` | flag | Disable citation collection | | `--swarm` | flag | Force swarm multi-agent workflow | | `--idempotency-key` | string | Deduplicate submissions | | `--traceparent` | string | W3C traceparent for distributed tracing | **Examples:** ```bash theme={"dark"} # Simple task shannon submit "What is 2+2?" --wait # Research with citations shannon submit "Latest advances in quantum computing" \ --force-research --research-strategy deep --wait # Cost-optimized with small model shannon submit "Summarize this text" --model-tier small --mode simple --wait # Specific model and provider shannon submit "Analyze trends" --model-override gpt-5-nano-2025-08-07 --provider-override openai --wait # Multi-agent swarm shannon submit "Compare top 3 cloud providers for AI workloads" --swarm --wait # Attach to a session shannon submit "Follow-up question" --session-id my-session --wait ``` **Output:** ``` Task submitted: Task ID: task-abc123 Workflow ID: workflow-xyz789 Waiting for completion... Result: 4 ``` ### status - Get task status ```bash theme={"dark"} shannon status TASK_ID ``` **Example:** ```bash theme={"dark"} shannon status task-abc123 ``` **Output:** ``` Task: task-abc123 Status: COMPLETED Progress: 100.0% Result: The answer is 4. ``` ### cancel - Cancel a task ```bash theme={"dark"} shannon cancel TASK_ID [--reason REASON] ``` **Example:** ```bash theme={"dark"} shannon cancel task-abc123 --reason "No longer needed" ``` ### pause - Pause a task Pauses at the next workflow checkpoint (not immediate). ```bash theme={"dark"} shannon pause TASK_ID [--reason REASON] ``` **Example:** ```bash theme={"dark"} shannon pause task-abc123 --reason "Review intermediate results" ``` ### resume - Resume a paused task ```bash theme={"dark"} shannon resume TASK_ID [--reason REASON] ``` **Example:** ```bash theme={"dark"} shannon resume task-abc123 --reason "Continue after review" ``` ### control-state - Get pause/cancel state ```bash theme={"dark"} shannon control-state TASK_ID ``` **Output:** ``` Task: task-abc123 Paused: True Cancelled: False Paused at: 2025-01-15T10:30:00 Pause reason: Review intermediate results ``` *** ## Streaming ### stream - Stream task events via SSE ```bash theme={"dark"} shannon stream WORKFLOW_ID [OPTIONS] ``` | Flag | Type | Description | | --------------- | ------ | --------------------------------------- | | `--types` | string | Comma-separated event types to filter | | `--traceparent` | string | W3C traceparent for distributed tracing | **Event types:** `WORKFLOW_STARTED`, `WORKFLOW_COMPLETED`, `LLM_PROMPT`, `LLM_PARTIAL`, `LLM_OUTPUT`, `TOOL_INVOKED`, `TOOL_OBSERVATION`, `APPROVAL_REQUESTED`, `APPROVAL_DECISION`, `ERROR_OCCURRED` **Examples:** ```bash theme={"dark"} # Stream all events shannon stream workflow-xyz789 # Stream only LLM output and completion shannon stream workflow-xyz789 --types LLM_OUTPUT,WORKFLOW_COMPLETED ``` **Output:** ``` Streaming events for workflow: workflow-xyz789 ------------------------------------------------------------ 10:30:01 WORKFLOW_STARTED: Task started 10:30:02 [agent-1] LLM_OUTPUT: The answer is 4. 10:30:03 WORKFLOW_COMPLETED: Task completed successfully ``` *** ## HITL Review (Human-in-the-Loop) ### review-get - Get review state ```bash theme={"dark"} shannon review-get WORKFLOW_ID ``` **Output:** ``` Status: reviewing Round: 2 Version: 3 Current plan: 1. Research topic 2. Analyze data 3. Write report Query: Research AI trends Conversation (2 messages): [system] (2025-01-15T10:00:00): Initial plan generated [user] (2025-01-15T10:05:00): Add error handling section ``` ### review-feedback - Submit feedback ```bash theme={"dark"} shannon review-feedback WORKFLOW_ID MESSAGE [--version N] ``` The `--version` flag enables optimistic concurrency control. **Example:** ```bash theme={"dark"} shannon review-feedback workflow-xyz789 "Add more detail on pricing" --version 3 ``` ### review-approve - Approve review plan ```bash theme={"dark"} shannon review-approve WORKFLOW_ID [--version N] ``` **Example:** ```bash theme={"dark"} shannon review-approve workflow-xyz789 --version 4 ``` ### approve - Approve/reject pending approval request ```bash theme={"dark"} shannon approve APPROVAL_ID WORKFLOW_ID [--approve | --reject] [--feedback TEXT] ``` `--approve` is the default. Use `--reject` to reject. **Examples:** ```bash theme={"dark"} # Approve shannon approve approval-001 workflow-xyz789 --feedback "Looks good" # Reject shannon approve approval-001 workflow-xyz789 --reject --feedback "Needs revision" ``` *** ## Sessions ### session-list - List sessions ```bash theme={"dark"} shannon session-list [--limit N] [--offset N] ``` | Flag | Default | Description | | ---------- | ------- | ---------------------- | | `--limit` | 50 | Max sessions to return | | `--offset` | 0 | Pagination offset | **Example:** ```bash theme={"dark"} shannon session-list --limit 10 ``` ### session-get - Get session details ```bash theme={"dark"} shannon session-get SESSION_ID [--no-history] ``` **Example:** ```bash theme={"dark"} shannon session-get my-session shannon session-get my-session --no-history ``` ### session-title - Update session title ```bash theme={"dark"} shannon session-title SESSION_ID TITLE ``` **Example:** ```bash theme={"dark"} shannon session-title my-session "Q1 Research Project" ``` ### session-delete - Delete a session ```bash theme={"dark"} shannon session-delete SESSION_ID ``` *** ## Schedules ### schedule-create - Create a recurring task ```bash theme={"dark"} shannon schedule-create NAME CRON QUERY [OPTIONS] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ------------------------------ | | `NAME` | Yes | Schedule name | | `CRON` | Yes | Cron expression | | `QUERY` | Yes | Task query to execute each run | **Options:** | Flag | Default | Description | | --------------------- | ------- | --------------------------------------------- | | `--description` | (none) | Schedule description | | `--timezone` | `UTC` | Timezone for cron evaluation | | `--force-research` | off | Enable research mode | | `--research-strategy` | (none) | `quick` \| `standard` \| `deep` \| `academic` | | `--budget` | (none) | Max budget per run in USD | | `--timeout` | (none) | Timeout per run in seconds | **Cron expression reference:** ``` MIN HOUR DAY MONTH WEEKDAY 0 9 * * 1-5 = Weekdays at 9:00 AM 0 */4 * * * = Every 4 hours 0 0 * * 1 = Every Monday at midnight 30 8 1 * * = First of month at 8:30 AM ``` **Examples:** ```bash theme={"dark"} # Daily research briefing shannon schedule-create "Daily AI News" "0 9 * * *" "Latest AI news summary" \ --timezone Asia/Tokyo --force-research --research-strategy quick # Weekly deep analysis shannon schedule-create "Weekly Market Report" "0 0 * * 1" \ "Comprehensive market analysis for the past week" \ --force-research --research-strategy deep --budget 5.0 ``` ### schedule-list - List schedules ```bash theme={"dark"} shannon schedule-list [--page N] [--page-size N] [--status ACTIVE|PAUSED] ``` **Example:** ```bash theme={"dark"} shannon schedule-list --status ACTIVE ``` **Output:** ``` Total: 3 sched-001 Daily AI News 0 9 * * * ACTIVE sched-002 Weekly Report 0 0 * * 1 ACTIVE sched-003 Hourly Check 0 * * * * PAUSED ``` ### schedule-get - Get schedule details ```bash theme={"dark"} shannon schedule-get SCHEDULE_ID ``` ### schedule-update - Update a schedule ```bash theme={"dark"} shannon schedule-update SCHEDULE_ID [OPTIONS] ``` | Flag | Description | | ----------------- | ----------------------------- | | `--name` | New name | | `--description` | New description | | `--cron` | New cron expression | | `--timezone` | New timezone | | `--query` | New task query | | `--budget` | New max budget per run (USD) | | `--timeout` | New timeout per run (seconds) | | `--clear-context` | Clear task context | **Example:** ```bash theme={"dark"} shannon schedule-update sched-001 --cron "0 10 * * *" --query "Updated news query" ``` ### schedule-pause - Pause a schedule ```bash theme={"dark"} shannon schedule-pause SCHEDULE_ID [--reason REASON] ``` ### schedule-resume - Resume a schedule ```bash theme={"dark"} shannon schedule-resume SCHEDULE_ID [--reason REASON] ``` ### schedule-delete - Delete a schedule ```bash theme={"dark"} shannon schedule-delete SCHEDULE_ID ``` ### schedule-runs - View execution history ```bash theme={"dark"} shannon schedule-runs SCHEDULE_ID [--page N] [--page-size N] ``` | Flag | Default | Description | | ------------- | ------- | -------------- | | `--page` | 1 | Page number | | `--page-size` | 10 | Items per page | **Output:** ``` Total runs: 42 2025-01-15T09:00:00 COMPLETED 1523 tokens $0.0032 2025-01-14T09:00:00 COMPLETED 1891 tokens $0.0041 2025-01-13T09:00:00 FAILED 0 tokens - ``` *** ## Tools ### tools-list - List available tools ```bash theme={"dark"} shannon tools-list [--category CATEGORY] ``` **Example:** ```bash theme={"dark"} shannon tools-list ``` **Output:** ``` Name Description -------------------------------------------------------------------------------- web_search Search the web for information calculator Evaluate mathematical expressions ``` ### tool-get - Get tool details ```bash theme={"dark"} shannon tool-get NAME ``` **Example:** ```bash theme={"dark"} shannon tool-get web_search ``` **Output:** ``` Tool: web_search Description: Search the web for information Category: research Parameters: { "query": { "type": "string", "description": "Search query" } } ``` ### tool-exec - Execute a tool directly ```bash theme={"dark"} shannon tool-exec NAME [--arguments JSON] [--session-id ID] ``` | Flag | Type | Description | | -------------- | ----------- | ----------------------------------------------- | | `--arguments` | JSON string | Tool arguments as a JSON object (default: `{}`) | | `--session-id` | string | Optional session ID for tool context | **Example:** ```bash theme={"dark"} shannon tool-exec web_search --arguments '{"query": "Shannon AI"}' ``` **Output:** ``` Success: True Text: Found 5 results for "Shannon AI" Output: { "results": [...] } Execution time (ms): 342 ``` *** ## Agents ### agents-list - List deterministic agents ```bash theme={"dark"} shannon agents-list ``` **Output:** ``` ID Category Tool Name ------------------------------------------------------------------------------------------ agent-001 analysis data_analyzer Data Analysis Agent agent-002 coding code_review Code Review Agent ``` ### agent-get - Get agent details ```bash theme={"dark"} shannon agent-get AGENT_ID ``` **Example:** ```bash theme={"dark"} shannon agent-get agent-001 ``` **Output:** ``` Agent: agent-001 Name: Data Analysis Agent Category: analysis Tool: data_analyzer Description: Analyzes structured data and produces reports Input schema: { "query": { "type": "string" } } ``` ### agent-exec - Execute a deterministic agent ```bash theme={"dark"} shannon agent-exec AGENT_ID --input JSON [--session-id ID] [--stream] ``` | Flag | Type | Description | | -------------- | ----------- | -------------------------------------------- | | `--input` | JSON string | Agent input as a JSON object (default: `{}`) | | `--session-id` | string | Optional session ID | | `--stream` | flag | Request streamed agent execution | **Example:** ```bash theme={"dark"} shannon agent-exec agent-001 --input '{"query": "Analyze Q4 trends"}' ``` **Output:** ``` Task ID: task-abc123 Workflow ID: workflow-xyz789 Agent ID: agent-001 Status: RUNNING ``` ### swarm-message - Send message to running swarm ```bash theme={"dark"} shannon swarm-message WORKFLOW_ID MESSAGE ``` **Example:** ```bash theme={"dark"} shannon swarm-message workflow-xyz789 "Focus on cost analysis" ``` **Output:** ``` Success: True Status: ACCEPTED ``` *** ## Files ### session-files - List session workspace files ```bash theme={"dark"} shannon session-files SESSION_ID [--path SUBDIR] ``` | Flag | Type | Description | | -------- | ------ | ------------------------------- | | `--path` | string | Optional workspace subdirectory | **Example:** ```bash theme={"dark"} shannon session-files my-session ``` **Output:** ``` Type Size Path -------------------------------------------------------------------------------- file 1234 report.md file 567 data.json dir 0 images/ ``` ### session-file-get - Download a workspace file ```bash theme={"dark"} shannon session-file-get SESSION_ID PATH ``` **Example:** ```bash theme={"dark"} shannon session-file-get my-session report.md ``` ### memory-files - List user memory files ```bash theme={"dark"} shannon memory-files ``` **Output:** ``` Type Size Path -------------------------------------------------------------------------------- file 2048 profile.md file 512 preferences.json ``` ### memory-file-get - Download a memory file ```bash theme={"dark"} shannon memory-file-get PATH ``` **Example:** ```bash theme={"dark"} shannon memory-file-get profile.md ``` *** ## Skills ### skills-list - List available skills ```bash theme={"dark"} shannon skills-list [--category CATEGORY] ``` **Example:** ```bash theme={"dark"} shannon skills-list shannon skills-list --category research ``` **Output:** ``` Name Version Category Description -------------------------------------------------------------------------------- web_search 1.0 research Search the web for information code_analysis 1.0 coding Analyze code structure ``` ### skill-get - Get skill details ```bash theme={"dark"} shannon skill-get NAME ``` **Example:** ```bash theme={"dark"} shannon skill-get web_search ``` ### skill-versions - List skill versions ```bash theme={"dark"} shannon skill-versions NAME ``` **Example:** ```bash theme={"dark"} shannon skill-versions web_search ``` *** ## Common Workflows ### Submit and stream results ```bash theme={"dark"} # Submit task, capture workflow ID, then stream shannon submit "Research quantum computing breakthroughs" --force-research --research-strategy deep # Output: Workflow ID: workflow-xyz789 shannon stream workflow-xyz789 --types LLM_OUTPUT,WORKFLOW_COMPLETED ``` ### HITL review loop ```bash theme={"dark"} # 1. Submit task that triggers review shannon submit "Create deployment plan for production" --wait # 2. Check review state shannon review-get workflow-xyz789 # 3. Provide feedback shannon review-feedback workflow-xyz789 "Add rollback procedure" # 4. Approve when satisfied shannon review-approve workflow-xyz789 ``` ### Schedule with monitoring ```bash theme={"dark"} # Create schedule shannon schedule-create "Daily Report" "0 9 * * 1-5" \ "Generate daily business report" --timezone America/New_York # Check runs shannon schedule-runs sched-001 # Pause during holidays shannon schedule-pause sched-001 --reason "Holiday break" # Resume shannon schedule-resume sched-001 ``` *** ## Exit Codes | Code | Meaning | | ---- | -------------------------------------------------- | | 0 | Success | | 1 | Error (task failure, API error, invalid arguments) |