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.
Installation
This installs the shannon CLI command. Verify with:
From source (development):
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon/clients/python
pip install -e .
Connection
Local (self-hosted)
shannon --base-url http://localhost:8080 submit "Hello world" --wait
Shannon Cloud
Register at https://shannon.run to get an API key, then:
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:
export SHANNON_BASE_URL=http://localhost:8080
export SHANNON_API_KEY=sk_your_key_here
# export SHANNON_BEARER_TOKEN=eyJ... # alternative to API key
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:
shannon [--base-url URL] [--api-key KEY] [--bearer-token TOKEN] COMMAND [OPTIONS]
Tasks
submit - Submit a task
shannon submit QUERY [OPTIONS]
| Argument | Required | Description |
|---|
QUERY | Yes | The task query string |
| 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 |
# 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
Task submitted:
Task ID: task-abc123
Workflow ID: workflow-xyz789
Waiting for completion...
Result: 4
status - Get task status
Example:
shannon status task-abc123
Task: task-abc123
Status: COMPLETED
Progress: 100.0%
Result: The answer is 4.
cancel - Cancel a task
shannon cancel TASK_ID [--reason REASON]
shannon cancel task-abc123 --reason "No longer needed"
pause - Pause a task
Pauses at the next workflow checkpoint (not immediate).
shannon pause TASK_ID [--reason REASON]
shannon pause task-abc123 --reason "Review intermediate results"
resume - Resume a paused task
shannon resume TASK_ID [--reason REASON]
shannon resume task-abc123 --reason "Continue after review"
control-state - Get pause/cancel state
shannon control-state TASK_ID
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
shannon stream WORKFLOW_ID [OPTIONS]
| Flag | Type | Description |
|---|
--types | string | Comma-separated event types to filter |
--traceparent | string | W3C traceparent for distributed tracing |
WORKFLOW_STARTED, WORKFLOW_COMPLETED, LLM_PROMPT, LLM_PARTIAL, LLM_OUTPUT, TOOL_INVOKED, TOOL_OBSERVATION, APPROVAL_REQUESTED, APPROVAL_DECISION, ERROR_OCCURRED
Examples:
# Stream all events
shannon stream workflow-xyz789
# Stream only LLM output and completion
shannon stream workflow-xyz789 --types LLM_OUTPUT,WORKFLOW_COMPLETED
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
shannon review-get WORKFLOW_ID
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
shannon review-feedback WORKFLOW_ID MESSAGE [--version N]
--version flag enables optimistic concurrency control.
Example:
shannon review-feedback workflow-xyz789 "Add more detail on pricing" --version 3
review-approve - Approve review plan
shannon review-approve WORKFLOW_ID [--version N]
shannon review-approve workflow-xyz789 --version 4
approve - Approve/reject pending approval request
shannon approve APPROVAL_ID WORKFLOW_ID [--approve | --reject] [--feedback TEXT]
--approve is the default. Use --reject to reject.
Examples:
# 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
shannon session-list [--limit N] [--offset N]
| Flag | Default | Description |
|---|
--limit | 50 | Max sessions to return |
--offset | 0 | Pagination offset |
shannon session-list --limit 10
session-get - Get session details
shannon session-get SESSION_ID [--no-history]
shannon session-get my-session
shannon session-get my-session --no-history
session-title - Update session title
shannon session-title SESSION_ID TITLE
shannon session-title my-session "Q1 Research Project"
session-delete - Delete a session
shannon session-delete SESSION_ID
Schedules
schedule-create - Create a recurring task
shannon schedule-create NAME CRON QUERY [OPTIONS]
| Argument | Required | Description |
|---|
NAME | Yes | Schedule name |
CRON | Yes | Cron expression |
QUERY | Yes | Task query to execute each run |
| 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 |
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
# 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
shannon schedule-list [--page N] [--page-size N] [--status ACTIVE|PAUSED]
shannon schedule-list --status ACTIVE
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
shannon schedule-get SCHEDULE_ID
schedule-update - Update a schedule
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 |
shannon schedule-update sched-001 --cron "0 10 * * *" --query "Updated news query"
schedule-pause - Pause a schedule
shannon schedule-pause SCHEDULE_ID [--reason REASON]
schedule-resume - Resume a schedule
shannon schedule-resume SCHEDULE_ID [--reason REASON]
schedule-delete - Delete a schedule
shannon schedule-delete SCHEDULE_ID
schedule-runs - View execution history
shannon schedule-runs SCHEDULE_ID [--page N] [--page-size N]
| Flag | Default | Description |
|---|
--page | 1 | Page number |
--page-size | 10 | Items per page |
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 -
shannon tools-list [--category CATEGORY]
Name Description
--------------------------------------------------------------------------------
web_search Search the web for information
calculator Evaluate mathematical expressions
shannon tool-get web_search
Tool: web_search
Description: Search the web for information
Category: research
Parameters:
{
"query": {
"type": "string",
"description": "Search query"
}
}
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 |
shannon tool-exec web_search --arguments '{"query": "Shannon AI"}'
Success: True
Text: Found 5 results for "Shannon AI"
Output:
{
"results": [...]
}
Execution time (ms): 342
Agents
agents-list - List deterministic agents
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
shannon agent-get AGENT_ID
shannon agent-get agent-001
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
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 |
shannon agent-exec agent-001 --input '{"query": "Analyze Q4 trends"}'
Task ID: task-abc123
Workflow ID: workflow-xyz789
Agent ID: agent-001
Status: RUNNING
swarm-message - Send message to running swarm
shannon swarm-message WORKFLOW_ID MESSAGE
shannon swarm-message workflow-xyz789 "Focus on cost analysis"
Success: True
Status: ACCEPTED
Files
session-files - List session workspace files
shannon session-files SESSION_ID [--path SUBDIR]
| Flag | Type | Description |
|---|
--path | string | Optional workspace subdirectory |
shannon session-files my-session
Type Size Path
--------------------------------------------------------------------------------
file 1234 report.md
file 567 data.json
dir 0 images/
session-file-get - Download a workspace file
shannon session-file-get SESSION_ID PATH
shannon session-file-get my-session report.md
memory-files - List user memory files
Output:
Type Size Path
--------------------------------------------------------------------------------
file 2048 profile.md
file 512 preferences.json
memory-file-get - Download a memory file
shannon memory-file-get PATH
shannon memory-file-get profile.md
Skills
skills-list - List available skills
shannon skills-list [--category CATEGORY]
shannon skills-list
shannon skills-list --category research
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
Example:
shannon skill-get web_search
skill-versions - List skill versions
shannon skill-versions NAME
shannon skill-versions web_search
Common Workflows
Submit and stream results
# 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
# 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
# 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) |
