> ## Documentation Index
> Fetch the complete documentation index at: https://artemiscity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/Documentation/architecture/routing-modes), 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:

```bash theme={null}
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

```text theme={null}
$ 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:

```bash theme={null}
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:

```yaml theme={null}
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.


## Related topics

- [Changelog](/Changelog/changelog.md)
- [Project structure](/Documentation/operations/project-structure.md)
- [Artemis Agentic Memory Layer](/Documentation/memory/MEMORY_INTEGRATION.md)
- [What Is Artemis City?](/Documentation/Introduction/what-is-artemis-city.md)
- [Why Not LLM Wrappers?](/Documentation/Introduction/why-not-llm-wrappers.md)