CLI Reference - Shannon

Installation

pip install shannon-sdk

This installs the shannon CLI command. Verify with:

shannon --help

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

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

Then simply:

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]

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:

# 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

shannon status TASK_ID

Example:

shannon status task-abc123

Output:

Task: task-abc123
Status: COMPLETED
Progress: 100.0%
Result: The answer is 4.

cancel - Cancel a task

shannon cancel TASK_ID [--reason REASON]

Example:

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]

Example:

shannon pause task-abc123 --reason "Review intermediate results"

resume - Resume a paused task

shannon resume TASK_ID [--reason REASON]

Example:

shannon resume task-abc123 --reason "Continue after review"

control-state - Get pause/cancel state

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

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:

# 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

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

shannon review-feedback WORKFLOW_ID MESSAGE [--version N]

The --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]

Example:

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

Example:

shannon session-list --limit 10

session-get - Get session details

shannon session-get SESSION_ID [--no-history]

Example:

shannon session-get my-session
shannon session-get my-session --no-history

session-title - Update session title

shannon session-title SESSION_ID TITLE

Example:

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]

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
  9     *     *      1-5     = Weekdays at 9:00 AM
  */4   *     *      *       = Every 4 hours
  0     *     *      1       = Every Monday at midnight
 8     1     *      *       = First of month at 8:30 AM

Examples:

# 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]

Example:

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

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

Example:

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

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

shannon tools-list [--category CATEGORY]

Example:

shannon tools-list

Output:

Name                      Description
--------------------------------------------------------------------------------
web_search                Search the web for information
calculator                Evaluate mathematical expressions

tool-get - Get tool details

shannon tool-get NAME

Example:

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

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:

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

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

shannon agent-get AGENT_ID

Example:

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

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:

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

shannon swarm-message WORKFLOW_ID MESSAGE

Example:

shannon swarm-message workflow-xyz789 "Focus on cost analysis"

Output:

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

Example:

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

shannon session-file-get SESSION_ID PATH

Example:

shannon session-file-get my-session report.md

memory-files - List user memory files

shannon 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

Example:

shannon memory-file-get profile.md

Skills

skills-list - List available skills

shannon skills-list [--category CATEGORY]

Example:

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

shannon skill-get NAME

Example:

shannon skill-get web_search

skill-versions - List skill versions

shannon skill-versions NAME

Example:

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)

Python SDK Quick Start Event Streaming

​Installation

​Connection

​Local (self-hosted)

​Shannon Cloud

​Environment Variables

​Global Options

​Tasks

​submit - Submit a task

​status - Get task status

​cancel - Cancel a task

​pause - Pause a task

​resume - Resume a paused task

​control-state - Get pause/cancel state

​Streaming

​stream - Stream task events via SSE

​HITL Review (Human-in-the-Loop)

​review-get - Get review state

​review-feedback - Submit feedback

​review-approve - Approve review plan

​approve - Approve/reject pending approval request

​Sessions

​session-list - List sessions

​session-get - Get session details

​session-title - Update session title

​session-delete - Delete a session

​Schedules

​schedule-create - Create a recurring task

​schedule-list - List schedules

​schedule-get - Get schedule details

​schedule-update - Update a schedule

​schedule-pause - Pause a schedule

​schedule-resume - Resume a schedule

​schedule-delete - Delete a schedule

​schedule-runs - View execution history

​Tools

​tools-list - List available tools

​tool-get - Get tool details

​tool-exec - Execute a tool directly

​Agents

​agents-list - List deterministic agents

​agent-get - Get agent details

​agent-exec - Execute a deterministic agent

​swarm-message - Send message to running swarm

​Files

​session-files - List session workspace files

​session-file-get - Download a workspace file

​memory-files - List user memory files

​memory-file-get - Download a memory file

​Skills

​skills-list - List available skills

​skill-get - Get skill details

​skill-versions - List skill versions

​Common Workflows

​Submit and stream results

​HITL review loop

​Schedule with monitoring

​Exit Codes

Installation

Connection

Local (self-hosted)

Shannon Cloud

Environment Variables

Global Options

Tasks

submit - Submit a task

status - Get task status

cancel - Cancel a task

pause - Pause a task

resume - Resume a paused task

control-state - Get pause/cancel state

Streaming

stream - Stream task events via SSE

HITL Review (Human-in-the-Loop)

review-get - Get review state

review-feedback - Submit feedback

review-approve - Approve review plan

approve - Approve/reject pending approval request

Sessions

session-list - List sessions

session-get - Get session details

session-title - Update session title

session-delete - Delete a session

Schedules

schedule-create - Create a recurring task

schedule-list - List schedules

schedule-get - Get schedule details

schedule-update - Update a schedule

schedule-pause - Pause a schedule

schedule-resume - Resume a schedule

schedule-delete - Delete a schedule

schedule-runs - View execution history

Tools

tools-list - List available tools

tool-get - Get tool details

tool-exec - Execute a tool directly

Agents

agents-list - List deterministic agents

agent-get - Get agent details

agent-exec - Execute a deterministic agent

swarm-message - Send message to running swarm

Files

session-files - List session workspace files

session-file-get - Download a workspace file

memory-files - List user memory files

memory-file-get - Download a memory file

Skills

skills-list - List available skills

skill-get - Get skill details

skill-versions - List skill versions

Common Workflows

Submit and stream results

HITL review loop

Schedule with monitoring

Exit Codes