CLI & Chat

The miminions console command is the primary surface for the framework: it manages agents, knowledge, workspaces, and execution sessions, and it hosts the interactive chat and one-shot prompt runtimes that drive a live Minion.

# Installed as a console script…
miminions --help

# …or run as a module
python -m miminions --help

State lives under ~/.miminions/

All persistent CLI state is stored as JSON under your home directory: config.json, auth.json, agents.json, knowledge.json, sessions.json, interactions.json, plus a workspaces/ tree. Set the MIMINIONS_HOME environment variable to relocate the whole directory (handy for tests and alternate deployments). JSON stores are written atomically, so an interrupted save can't leave a corrupt file behind. On the first invocation of any command, MiMinions bootstraps a default workspace and a default agent so the chat/prompt commands work out of the box.

# Explicitly initialize (or verify) default bootstrap state
miminions init

# Repair bootstrap state and restore missing default templates
miminions init --force

init is an explicit, user-facing bootstrap/repair command over the same default setup logic used on first command run. The --force option re-runs bootstrap repair so missing default workspace template files are recreated without overwriting existing customized files.

Command groups at a glance

• auth — local sign-in, status, and config
• config — get/set top-level CLI defaults (default_workspace, default_agent)
• export/import — backup and restore agents/tasks/knowledge JSON data
• agent — manage and run agent records
• tool — discover, execute, and trace tools and tool sessions
• chat — interactive conversation with memory distillation
• prompt — one-shot prompt to the runtime
• knowledge — versioned knowledge entries
• workspace — workspaces, rules, and on-disk scaffolding
• gateway — local gateway runtime, cron jobs, and gateway sessions

---

chat

An interactive, async conversation with a live Minion bound to a workspace.

# Start a chat in the default workspace
miminions chat start

# Pick a workspace by id or name
miminions chat start --workspace my-project

# Resume a prior conversation by session id
miminions chat start --session 20260621T101500000000Z_a1b2c3d4

# Show tool calls, token usage and latency per turn
miminions chat start --verbose

Option	Description
--workspace <id\|name>	Workspace to run in. Defaults to the configured default workspace.
--session <id>	Resume an existing session id (loads prior history into the LLM context).
--verbose	Print each tool call and per-turn token usage / latency to stderr.

Inside the loop, type a message and press Enter — the reply streams to the terminal as it is generated. Type /exit or /quit (or send EOF / Ctrl-C) to end the session. Every turn is appended to the session transcript, and on exit a background memory distillation pass runs.

Workspace : my-project
Session   : 20260621T101500000000Z_a1b2c3d4
Model     : openai/gpt-oss-20b:free via OpenRouter
Type '/exit' or '/quit' to end the session.

> summarize the project goals
...
> /exit
Session ended.

Needs an LLM backend

Chat (and prompt) call the live model. With the default OpenRouter provider you must export OPENROUTER_API_KEY — without it, agent construction fails with a clear ValueError. Errors during a turn are shown as an [error] ... line; if a reply was partially streamed before the error, the partial text is kept in the transcript alongside the error marker. See Agent for switching providers.

Bounded LLM context (how it works)

Before each turn the in-memory history passed to the LLM is capped at the most recent 40 messages via trim_message_history, cutting only at a user-prompt turn boundary so tool call/return pairs are never split. The JSONL transcript on disk always stays complete — only the model's context window is bounded.

Session resumption (how it works)

Passing --session <id> loads the append-only .jsonl transcript from JsonlSessionStore and converts it back into native pydantic-ai messages via load_as_pydantic_messages(), giving the LLM full conversational context from prior runs. New sessions get an id of the form YYYYMMDDTHHMMSSffffffZ_<8-char-uuid>. Transcripts live under <workspace_root>/sessions/.

Background distillation (how it works)

When the chat loop ends, a MemoryDistiller runs in the finally block over the session transcript. It promotes extracted memory across three tiers — Tier 1 → HISTORY.md, Tier 2 → MEMORY.md "Project Facts", Tier 3 → the global SQLite insight DB at ~/.miminions/global_memory.db. If a real model is available it uses create_llm_filter(model) to extract facts; otherwise it runs the pipeline with an empty placeholder filter. Distillation failures are caught and reported as a warning rather than crashing your terminal. See Memory for the full pipeline.

---

prompt

A one-shot prompt to the Minion runtime — no interactive loop. The prompt text is a positional argument.

# Ask once in the default workspace
miminions prompt ask "Summarize the latest changes"

# Target a specific workspace and session
miminions prompt ask "Draft a release note" --workspace my-project --session my-session

Argument / Option	Description
PROMPT...	The prompt (one or more words, joined). Required.
--workspace <id\|name>	Workspace id or name. Default: default.
--session <id>	Optional existing session id; a new one is created if omitted.

The command builds a workspace context string via ContextBuilder, records both the user prompt and assistant reply to the session transcript, and prints the reply. If the workspace does not exist it is created and its files are initialized.

---

auth

Local authentication and configuration.

Local stub, not a remote server

auth signin does not contact any remote service. It validates a username/password locally and writes an auth.json marker that the require_auth gate checks. There is no account system behind it.

miminions auth signin --username alice         # prompts for password
miminions auth status
miminions auth signout

# Configure public access and timeout
miminions auth config --public-access true
miminions auth config --auth-timeout 60
miminions auth config                          # show current config

Command	Options	Description
signin	--username, --password, --timeout	Sign in locally (prompts for any missing credential). Writes auth.json.
signout	—	Clear the local auth marker.
status	—	Show signed-in user and whether public access is enabled.
config	--public-access <bool>, --auth-timeout <int>	Read or set config; with no options, prints current settings. Timeout must be ≥ 5 seconds.

Public access bypasses the gate

miminions auth config --public-access true lets gated commands run without signing in (they print a "Public access mode." warning). Useful for local development.

---

config

Top-level configuration access for defaults used by CLI commands.

# Read one key
miminions config get default_workspace
miminions config get default_agent

# Set one key (workspace resolves id/prefix/name to canonical id)
miminions config set default_workspace my-project

# Set default agent (must already exist in agents.json)
miminions config set default_agent researcher

Command	Description
get <key>	Print one value from config.json.
set <key> <value>	Validate and update one value in config.json.

Supported keys:

• default_workspace
• default_agent

auth config vs config

miminions auth config manages authentication flags (public_access, auth_timeout). miminions config manages top-level default routing (default_workspace, default_agent).

---

export / import

Backup and restore CLI record stores for cross-machine migration.

# Export agents/tasks/knowledge to one backup file
miminions export --output ./miminions-backup.json

# Import and merge with existing records
miminions import --input ./miminions-backup.json --mode merge

# Import and replace existing records
miminions import --input ./miminions-backup.json --mode replace

Command	Options	Description
export	--output <path>	Export agents.json, and knowledge.json into one backup JSON file.
import	--input <path>, --mode merge\|replace	Restore backup data into agents.json, and knowledge.json.

--mode merge keeps existing records and overlays imported ids. --mode replace replaces each target store with imported data.

---

agent

Manage persisted agent records and drive a live Minion built from them. Agent records are CLI extensions of the core Minion runtime, and their default CLI tools remain available through tool-list, tool-info, tool-search, and tool-run.

All commands that take an agent id accept it as an optional positional argument. When omitted, the default_agent from ~/.miminions/config.json is used.

miminions agent list
miminions agent show researcher
miminions agent add --name "Researcher" --description "Finds things" --type assistant
miminions agent update researcher --description "Updated"
miminions agent set-goal researcher --goal "Summarize today's notes"
miminions agent run researcher
miminions agent run                            # uses default_agent
miminions agent ask researcher --prompt "what time is it in UTC?"
miminions agent ask --prompt "what time is it in UTC?"  # uses default_agent
miminions agent remove researcher

Records & lifecycle

Command	Options	Description
list	—	List all agent records with status and description.
show <ref>	—	Show full details for one agent by id, id prefix, or exact name.
add	--name, --description, --type	Create a record (id is the slugified name; a _2, _3, … suffix is appended if the id is already taken). All three are prompted if omitted.
update <id>	--name, --description, --type	Update fields on an existing record.
remove <id>	—	Delete a record (asks for confirmation).
set-goal [id]	--goal	Store a goal used by run. id defaults to default_agent.
run [id]	—	Build the runtime and execute the stored goal. id defaults to default_agent. Requires a goal to be set.
ask [id]	--prompt	One-off prompt to the agent without mutating its stored goal. id defaults to default_agent.

show <ref> accepts an exact id, an id prefix, or an exact agent name.

run --async is not functional

The --async flag on agent run currently prints a TODO placeholder and does not execute anything asynchronously. Use plain miminions agent run [id] for real execution.

Tool

The top-level tool category builds an agent's runtime and operates on its registered tools. The agent id is optional and defaults to the configured default agent.

Command	Arguments / Options	Description
list [id]	—	List the agent's tool names and descriptions.
info [id] <tool>	—	Show a tool's description and JSON parameter schema.
search [id] <query>	—	Search tools by name/description (substring).
execute [id] <tool>	--arguments '<json>'	Execute one tool with a JSON-object argument map and print the structured result (status, result/error, timing).

miminions tool list researcher
miminions tool list                            # uses default_agent
miminions tool execute researcher cli_add --arguments '{"a": 2, "b": 3}'
miminions tool execute cli_add --arguments '{"a": 2, "b": 3}'  # uses default_agent

MCP servers

MCP stdio servers are configured per agent. Registration stores the executable and its arguments; the server is started only while an agent command is using its tools.

Command	Arguments / Options	Description
mcp-add <id> <server>	--command, repeatable --arg	Register a stdio MCP server without starting it.
mcp-list <id>	—	List the agent's registered MCP servers.
mcp-remove <id> <server>	--yes	Remove a registration, with confirmation unless --yes is supplied.

miminions agent mcp-add researcher files --command python --arg files_server.py
miminions agent mcp-list researcher
miminions agent mcp-remove researcher files --yes

---

knowledge

Versioned knowledge entries persisted to knowledge.json. Each content change records a new version.

miminions knowledge list
miminions knowledge add --title "Deploy Steps" --content "..." --category ops --tags "deploy,ci"
miminions knowledge update <id> --content "revised steps"
miminions knowledge version <id>
miminions knowledge revert <id> --version 1.0
miminions knowledge show <id>
miminions knowledge remove <id>

Command	Options	Description
list	--json	List entries with version, category, and status.
add	--title, --content, --category, --tags	Create an entry at version 1.0.
update <id>	--title, --content, --category, --tags	Update fields; a content change bumps the version.
revert <id>	--version	Restore content from a recorded version.
version <id>	—	Show the version history.
customize <id>	--template, --format	Apply a template and/or render as json / markdown / plain.
show <id>	--json	Print full entry detail.
remove <id>	—	Delete an entry (asks for confirmation).

Version bumps

Updating --content to a new value appends a snapshot and increments the version by +0.1 (e.g. 1.0 → 1.1). Use revert --version <v> to roll back to any recorded snapshot.

---

workspace

Manage workspaces — the in-memory/on-disk model of nodes and rules plus the on-disk prompt/ memory/ skills/ sessions/ data/ scaffolding.

miminions workspace list
miminions workspace add --name "My Project" --description "Demo"
miminions workspace add --name "Demo" --sample --init-files
miminions workspace show <id|name>
miminions workspace update <id> --name "Renamed"
miminions workspace set-state <id> --key priority --value high
miminions workspace remove <id>

Workspace references accept either a full id, an id prefix, or the workspace name.

Workspace lifecycle

Command	Options	Description
list	--json	List workspaces with node/rule counts.
add	--name, --description, --sample, --init-files, --root-path	Create a workspace. --sample seeds example nodes/rules; --init-files scaffolds the on-disk folder; --root-path overrides where files are written.
show <ref>	--json	Print full workspace detail (nodes, rules, inherited rules, state).
update <ref>	--name, --description	Rename or re-describe.
remove <ref>	--force	Delete a workspace (confirm unless --force).
set-state <ref>	--key, --value	Set a state value (value is parsed as JSON when possible).
init-files <ref>	--path	Scaffold prompt/memory/skills/sessions/data files for an existing workspace.

Rules

Command	Options	Description
add-rule <ref>	--name, --description, --priority, --enabled/--disabled, --condition, --action	Add a rule. --priority is LOW/MEDIUM/HIGH/CRITICAL. --condition/--action take a JSON object (or a bare string treated as {"type": "<value>"}).
remove-rule <ref> <rule>	—	Remove a rule by id, id prefix, or name.

miminions workspace add-rule my-project \
  --name "escalate" --priority HIGH \
  --condition '{"type":"state_equals","key":"priority","value":"high"}' \
  --action '{"type":"assign_task","message":"escalate now"}'

---

Tool sessions and history

A live tool-execution runtime: start a session, register tool modules, run individual tools, and review the recorded interactions. Each tool run is captured as a WorkflowRun trace and persisted to interactions.json.

# 1. Start a session
miminions tool session start --name demo

# 2. Register a Python module that defines GenericTool instances
miminions tool add ./my_tools.py

# 3. Run a tool with KEY=VALUE inputs
miminions tool session execute my_tool --input city=Tokyo --input units=metric

# 4. Review what happened
miminions tool history list
miminions tool history show 0

# 5. Stop the session
miminions tool session stop

Sessions

Command	Options	Description
session start	--name	Start a new session (only one active at a time).
session stop	—	Stop the active session.
session list	--json	List all sessions with status.

Tools & runs

Command	Arguments / Options	Description
add <path.py>	—	Load GenericTool instances from a .py file into the active session.
session execute <tool>	--input KEY=VALUE (repeatable)	Execute a registered tool with string inputs; prints result/error and records a WorkflowRun.
test	--prompt	Run every registered tool with its default parameters and record the batch as one WorkflowRun.

History

Command	Arguments / Options	Description
history list	--session-id, --json	List recorded WorkflowRuns for a session (defaults to the active one).
history show <index>	--session-id, --json	Print the full JSON of a recorded WorkflowRun.

Tool modules

tool add imports any module-level objects that are GenericTool instances. Define your tools with @tool(...) or create_tool(...) from miminions.tools (see Tools) and point tool add at the file.

---

gateway

Manage the local gateway runtime for a workspace, plus gateway cron jobs and gateway-specific sessions. The command group is registered, but it still exposes local runtime controls rather than hosted channel integrations.

miminions gateway status --workspace Demo
miminions gateway start --workspace Demo
miminions gateway cron list --workspace Demo
miminions gateway cron exec --workspace Demo <job-id>
miminions gateway sessions list --workspace Demo

Command	Options	Description
status	--workspace	Show workspace gateway paths, session count, and cron job count.
start	--workspace, --no-cron, --log-level	Start the local gateway runtime until interrupted.
cron list	--workspace, --all	List gateway cron jobs.
cron add-every	--workspace, --name, interval option, --message	Add a recurring interval job.
cron add-at	--workspace, --name, --at, --message	Add a one-shot ISO-datetime job.
cron add-cron	--workspace, --name, --expr, --tz, --message	Add a cron-expression job; requires croniter.
cron remove / enable / disable / exec	--workspace plus job id	Manage or trigger an existing cron job.
sessions list / show / delete	--workspace plus session options	Inspect or delete gateway sessions.

Workspace root required

Gateway commands resolve an existing workspace and require it to have a root_path. Run miminions workspace init-files <workspace> first if needed.

---

Where things live

Path	Contents
~/.miminions/config.json	CLI config + default workspace/agent ids
~/.miminions/auth.json	Local sign-in marker
~/.miminions/agents.json · knowledge.json	Record stores for the respective groups
~/.miminions/sessions.json · interactions.json	Tool sessions and recorded traces
~/.miminions/workspaces/	Per-workspace on-disk folders (prompt/ memory/ skills/ sessions/ data/)
~/.miminions/global_memory.db	Tier-3 global SQLite insight store (written by chat distillation)

Related

• Agent — the Minion runtime the CLI drives
• Workspaces — nodes, rules, and on-disk layout
• Memory — the three-tier memory and distillation pipeline