CLI

This guide documents the CLI binaries exposed by antikythera-cli.

Binary map

flowchart LR
    CLI_CRATE[antikythera-cli]
    CLI_CRATE --> MAIN[antikythera]
    CLI_CRATE --> CONFIG[antikythera-config]
    MAIN --> STDIO[mode: stdio]
    MAIN --> SETUP[mode: setup]
    MAIN --> MULTI[mode: multi-agent]
    MAIN --> HARNESS[mode: wasm-harness]
    CONFIG --> PC[app.pc]

Overview

The CLI crate exposes two binaries:

Runtime provider and model selection are owned by the CLI layer. antikythera-core stays model-agnostic and only executes against the runtime client configuration that the CLI has already materialized.

antikythera

Runtime modes

The main binary accepts a --mode flag:

Execution flow

flowchart TD
    START[Run antikythera] --> LOAD[Load app.pc config]
    LOAD --> BUILD[Build McpClient]
    BUILD --> PARSE[Parse --mode]
    PARSE --> STDIO[mode = stdio]
    PARSE --> SETUP[mode = setup]
    PARSE --> MULTI[mode = multi-agent]
    PARSE --> HARNESS[mode = wasm-harness]
    STDIO --> CHAT[Interactive ratatui chat workspace]
    SETUP --> WIZARD[Config wizard menu]
    MULTI --> ORCH[MultiAgentOrchestrator dispatch]
    HARNESS --> WASM[Host-FFI probe over WASM runtime exports]

Interactive TUI UX

The stdio mode now launches a ratatui-based workspace with:

1. A conversation panel that keeps the latest chat and tool trace visible. While a response is in flight it shows a live streaming preview of the incoming tokens (if the provider supports streaming).
2. A context sidebar showing provider, model, session, and configured backends.
3. A prompt box with slash-command recommendations as soon as the input starts with /.
4. Inline commands such as /help, /providers, /use <provider> [model], /model <name>, /config, /tools, /agent, /reset, and /exit.
5. A Settings overlay (press F2) showing the full active config as TOML.
6. A History browser overlay (press F3) listing saved conversations with open / rename / delete actions.
7. A health status dot in the footer that reflects live provider health (green = healthy, yellow = degraded, red = failing).

Use Tab to autocomplete the first command suggestion, Enter to submit, and Esc to quit.

Run it

# Default mode: stdio (interactive chat)
cargo run -p antikythera-cli --bin antikythera

# Explicit mode selection
cargo run -p antikythera-cli --bin antikythera -- --mode stdio
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider gemini --model gemini-2.0-flash
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider openai --model gpt-4o-mini
cargo run -p antikythera-cli --bin antikythera -- --mode stdio --provider ollama --model llama3.2 --provider-endpoint http://127.0.0.1:11434
cargo run -p antikythera-cli --bin antikythera -- --mode setup
cargo run -p antikythera-cli --bin antikythera -- --mode multi-agent --agents agents.json --task "Write a summary"
cargo run -p antikythera-cli --bin antikythera -- --mode wasm-harness --wasm target/wasm32-wasip1/release/antikythera_sdk.wasm --task "Smoke test"

# Task shortcuts
task run-tui
task run
task run-wasm
task setup-config PROVIDER_ID=openai PROVIDER_TYPE=openai PROVIDER_ENDPOINT=https://api.openai.com PROVIDER_API_KEY=OPENAI_API_KEY MODEL_NAME=gpt-4o-mini

task run now bootstraps app.pc automatically when needed and opens the interactive TUI directly. Change provider/model from inside the TUI with commands such as /use gemini gemini-2.0-flash or /model gpt-4o-mini instead of passing runtime shell arguments.

Common flags

Multi-agent flags

Agent profile JSON format:

[
  {
    "id": "writer",
    "name": "Writer Agent",
    "role": "writer",
    "system_prompt": "You write clear and concise content.",
    "max_steps": 8
  }
]

antikythera-config

What it does

antikythera-config manages the Postcard-based config file shared across all framework surfaces.

Config workflow

flowchart LR
    INIT[init] --> FILE[app.pc]
    FILE --> SHOW[show]
    FILE --> GET[get]
    FILE --> SET[set]
    FILE --> ADD[add-provider]
    FILE --> MODEL[set-model]
    FILE --> EXPORT[export JSON]
    EXPORT --> IMPORT[import JSON]
    FILE --> STATUS[status]

Run it

cargo run -p antikythera-cli --bin antikythera-config -- --help

Available subcommands

Supported fields for get and set

get providers is also supported and returns the provider list as JSON.

Example workflow

# Create default file
cargo run -p antikythera-cli --bin antikythera-config -- init

# Add an OpenAI provider
cargo run -p antikythera-cli --bin antikythera-config -- add-provider openai openai https://api.openai.com OPENAI_API_KEY

# Set the default model
cargo run -p antikythera-cli --bin antikythera-config -- set-model openai gpt-4o-mini

# Check current status
cargo run -p antikythera-cli --bin antikythera-config -- status

Provider limitations

antikythera-config init now seeds provider templates for gemini, openai, and ollama, including their common default endpoints and model presets. add-provider also normalizes aliases such as google-ai -> gemini and localai -> ollama.

API consistency rules

To keep CLI discoverability and public contracts stable:

Deprecated alias map

Current aliases are maintained only for compatibility and are documented in the deprecation policy.

Related documents

• CONFIG.md for the config format and serialization model
• BUILD.md for build commands and component workflows
• PRODUCT_SCOPE.md for deployment targets and feature flags
• DEPRECATION_POLICY.md for deprecation lifecycle and CI enforcement