Kernel CLI

Drive the Artemis City kernel from a terminal with one-shot, plan-file, or interactive modes.

The Kernel CLI is the terminal entry point to the Artemis City kernel. Use it to issue a single command, execute a plan file, or open an interactive session for ongoing requests. The CLI boots the kernel, routes each command through the agent router, and prints the response from the agent that handled it.

When to use it

• Smoke-testing a kernel deployment without standing up the dashboard or API.
• Scripting one-shot commands (system status, memory queries, planning prompts) from CI or shell tooling.
• Exploring routing behavior interactively while developing new agents or routes.

Prerequisites

• A working install of the Artemis City package so app.kernel is importable.
• Run from the repository root (or any directory where the installed app package is on PYTHONPATH).

Usage

Invoke the CLI as a Python module:

python -m app.kernel.cli "system status"

Modes

Mode	Invocation	Behavior
One-shot command	python -m app.kernel.cli "<command>"	Boots the kernel, processes the command once, prints the result, and exits.
Plan file	python -m app.kernel.cli --plan path/to/plan.yaml	Executes a plan file through the kernel and prints the result.
Interactive	python -m app.kernel.cli (no arguments)	Opens an artemis> prompt. Type commands until you exit, quit, or send Ctrl+C.

Interactive session

$ python -m app.kernel.cli
Welcome to Artemis-City Kernel (v1.0)
Type 'exit' to quit.
artemis> system status
[Kernel] daemon responded:
[daemon] Acknowledged: system status
artemis> draft a roadmap for Q3
[Kernel] planner responded:
[planner] Draft plan for: draft a roadmap for Q3
artemis> exit

If the kernel fails to boot, the CLI prints Fatal: Kernel failed to boot. with the underlying error and exits with status 1.

Legacy entry point

The CLI implementation was consolidated under app.kernel.cli. The historical src.interface.artemis_cli module is preserved as a thin compatibility wrapper, so existing scripts and shortcuts keep working:

python -m src.interface.artemis_cli "system status"

Both invocations dispatch through the same parser and kernel. The make cli target wraps this legacy module and automatically sources .env before launching, so locally configured MCP_API_KEY and MCP_BASE_URL values are available to the kernel without extra exports. Prefer python -m app.kernel.cli for new tooling.

Built-in agents

The kernel ships with two concrete agents that handle routed commands and record each interaction to the memory bus:

• daemon — system anchor and memory interface. Handles system, status, health, config, memory, and daemon keywords. Also serves as the default fallback when a routed persona has no concrete agent yet.
• planner — drafts execution plans for planning prompts (roadmaps, blueprints, schedules).

Additional personas (artemis, pack_rat, copilot) are declared in agent_router.yaml but do not yet have concrete implementations. Commands routed to them fall back to the daemon, and the kernel logs the fallback so the gap is visible rather than silently mislabelled. The response header reports the agent that actually handled the command, which may differ from the routed persona name.

Configuring routes

Routes are declared in app/kernel/agent_router.yaml. Each entry maps a persona name to a role, keyword list, and action description:

agents:
  planner:
    role: "Planning and reasoning"
    keywords: ["plan", "roadmap", "blueprint", "schedule"]
    action_description: "Drafting an execution plan."
  daemon:
    role: "System anchor, memory interface"
    keywords: ["memory", "system", "daemon", "config", "status", "health"]
    action_description: "Querying system status or memory interface."

To add a new keyword route, append it to the agents list. To wire a new concrete agent, add the class under app/kernel/agents/ and register it in the kernel’s agent factory.