#ai — providers, models, agents and chats
The AI module gives this host an agent that knows it: providers and their API keys, a model catalogue, agents with instructions and attachments, tools and skills, chats in the terminal, one-shot prompts, and a background queue that a keeper service drains.
Everything the commands write lives in database/storage/ai/ai.db. Everything that comes from a file — the shipped agents and skills — is owned by that file and rewritten by aegis ai setup; the command line owns only the rows it created itself.
aegis ai # the command list and examplesaegis ai help # the sameaegis ai providers listEvery listing command also accepts aegis --json ai …, which prints one JSON object instead of the table. The flag goes before the group, on the root command.
#The catalogue at a glance
| Command | What it manages |
|---|---|
aegis ai providers | endpoints, their keys and which one is the default |
aegis ai models | context windows, output limits, capabilities and prices |
aegis ai setup | the whole catalogue, in dependency order, in one step |
aegis ai agents | instructions, loop limits and what an agent attaches |
aegis ai tools | the tool catalogue, grouped in packs |
aegis ai skills | prompt blocks agents carry |
aegis ai chat | a conversation in the terminal |
aegis ai prompt | one turn, printed, or queued in the background |
aegis ai jobs | the background queue and its history |
aegis ai answer | the questions a background turn is waiting on |
aegis ai daemon | the background worker, in the foreground |
#Where the data lives
config/ai.toml credentials, defaults, limitsdatabase/storage/ai/ai.db the catalogue and every transcriptstorage/ai/agents/<slug>/agent.md system agents (file-owned)storage/ai/skills/<category>/<slug>/skill.mdrun/ai.pid, run/ai.lock, run/ai.heartbeat the background daemonlogs/ai.log what the daemon printedProviders come from config/ai.toml ([providers.<slug>]) and from the driver declarations under app/modules/ai/providers/; a sync writes both. An agent or skill whose source_path is set is read-only from the command line: the file owns it, and a sync reconciles its row. One created with add has no file and is edited and removed here.
#Providers
A provider is one endpoint, one key and one driver. The driver is code: it decides how a request is shaped, so a provider named in the config whose driver this build does not ship is reported instead of guessed.
#aegis ai providers list
Print every provider with the source of the key it uses, its default flag, the number of models it has and its endpoint. The key column reads db when set-key wrote the secret, config when it comes from config/ai.toml, and missing when there is none.
aegis ai providers list| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis ai providers listaegis --json ai providers listslug driver default status key models url──────── ──────── ─────── ────── ─────────── ────── ────────────────────────────deepseek deepseek yes active db …a1b2 2 https://api.deepseek.com/v1xai xai active config …9f3c 8 https://api.x.ai/v1When the table is empty the command says so and returns 0:
ℹ no provider yet; run `aegis ai providers sync`#aegis ai providers show
Print one provider as a key/value block, followed by its models in the same shape aegis ai models list uses. The key is shown by source and masked to its last four characters.
aegis ai providers show <slug>| Argument | Default | Meaning |
|---|---|---|
slug | required | provider slug, for example deepseek |
aegis ai providers show deepseekaegis ai providers show xaislug deepseekname DeepSeekdriver deepseekapi_url https://api.deepseek.com/v1status activedefault yeskey db …a1b2provider model context output tools reasoning──────── ──────────────── ─────── ────── ───── ──────────────────deepseek deepseek-flash 1M 384k yes none, low, high, maxdeepseek deepseek-v4-pro 1M 384k yes none, low, high, maxAn unknown slug prints ✖ unknown provider: openai and exits 1.
#aegis ai providers sync
Write the providers declared in config/ai.toml and every model declared by the drivers into ai.db. This is the same handler as aegis ai models sync: both write the whole catalogue. It never copies a key out of the config, keeps the key already stored on a row, and never deletes a row, so it is safe after every deploy.
aegis ai providers sync| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis ai providers syncaegis ai providers sync && aegis ai providers list✔ 2 providers, 10 models, 60 pricesA provider in the config that this build has no driver for is reported on stderr, and the rest of the sync still runs:
⚠ xai-experimental: no driver for that provider in this build✔ 2 providers, 10 models, 60 prices#aegis ai providers set-key
Store an API key on a provider row. The database wins over the config, so this is how a key is overridden without editing config/ai.toml. Without --key the value is read from the terminal with echo off, which keeps it out of the shell history.
aegis ai providers set-key <slug> --key <secret>| Option | Default | Meaning |
|---|---|---|
--key | "" | the secret; asked for when omitted |
aegis ai providers set-key deepseekaegis ai providers set-key xai --key "xai-…"api key for deepseek:✔ deepseek: key stored (…a1b2)An empty answer, or a key for an unknown provider, exits 1 with a message. The full key is never printed.
#Models
A model row carries the facts a provider API does not report: context window, output limit, feature flags, aliases, reasoning efforts and effective-dated prices. A sync writes every model the drivers declare; it never deletes one.
#aegis ai models list
Print the models, one per row, with the provider they belong to. Context and output are shortened (1M, 384k); a model that declares neither shows blank cells.
aegis ai models list --provider <slug> --all| Option | Default | Meaning |
|---|---|---|
--provider | "" | only the models of this provider slug |
--all | off | include the models marked inactive |
aegis ai models listaegis ai models list --provider deepseekaegis ai models list --allprovider model context output tools reasoning──────── ──────────────── ─────── ────── ───── ──────────────────deepseek deepseek-flash 1M 384k yes none, low, high, maxdeepseek deepseek-v4-pro 1M 384k yes none, low, high, maxxai grok-4.7 yes low, medium, high, xhighreasoning lists the effort levels the model accepts, or no when it has none. An empty catalogue prints:
ℹ no model yet; run `aegis ai providers sync`#aegis ai models sync
Write the declared models, their feature flags and their prices into ai.db. Prices are effective-dated: an unchanged number is left alone, a changed one closes the old row and opens a new one, so a past turn can be repriced with the rate that was valid when it ran.
aegis ai models sync| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis ai models syncaegis ai models sync && aegis ai models list✔ 2 providers, 10 models, 60 prices#Setup
#aegis ai setup
Write the whole catalogue in the order the dependencies allow: providers, then models and prices, then tools, then skills, then agents. Every step is an upsert; nothing edited by hand is lost and a row whose file disappeared is archived rather than deleted. It prints one animated line while it works, then a summary. It does not start the daemon.
aegis ai setup --check| Option | Default | Meaning |
|---|---|---|
--check | off | ask every provider that has a key for its model list |
aegis ai setupaegis ai setup --check✔ Aegis AI systems ready in 1.6sproviders 2 (keys: deepseek: db, xai: config)models 10tools 41 in 12 packsskills 10agents 2ℹ next: aegis ai prompt "salut" --agent aegisℹ aegis ai daemon startWith --check, a second table reports whether each key works. One request per provider, no retries, and the key is never printed:
provider result detail──────── ────── ────────deepseek ok 2 modelsxai failed HTTP 401A provider with no key at all reports no key. The command keeps its exit code 0 even when a check fails; the table is the answer.
#Agents
An agent is identity, instructions, loop limits, a model and the tools, skills and sub-agents it attaches. The three kinds are master, sub-agent and utility. The shipped aegis (master) and scout (read-only sub-agent) live as files under storage/ai/agents/; the command line can attach and detach things on them but cannot edit or delete their rows.
#aegis ai agents list
Print every agent with its kind, model, step limit, parallelism and attachment counts. steps is the agent's own max_steps; parallel is yes only when the agent may run sub-agents and tools concurrently.
aegis ai agents list --kind <kind>| Option | Default | Meaning |
|---|---|---|
--kind | "" (all) | master, sub-agent or utility |
aegis ai agents listaegis ai agents list --kind sub-agentslug kind model steps parallel tools skills status───── ───────── ────────────── ───── ──────── ───── ────── ──────aegis master deepseek-flash 25 yes 41 10 activescout sub-agent deepseek-flash 12 24 10 activeAn empty catalogue prints ℹ no agent yet; run aegis ai setup``.
#aegis ai agents show
Print one agent's fields, then its instructions, then three tables: attached tools, skills and sub-agents. An empty attachment block prints (none).
aegis ai agents show <slug>| Argument | Default | Meaning |
|---|---|---|
slug | required | agent slug, for example aegis |
aegis ai agents show aegisaegis ai agents show scoutslug aegisname Aegiskind mastermodel deepseek-flashstatus activemax_steps 25parallel yessource /aegis/storage/ai/agents/aegis/agent.md# Who you areYou are Aegis, the system agent of this host. …tools: tool pack status ─────────────── ─────── ────── aegis.command aegis active files.read files active shell.run shell activeskills: skill name category ───────────────── ────────────────── ──────── platform-overview Platform overview aegis conventions Project conventions aegissub-agents: agent name kind ───── ───── ───────── scout Scout sub-agentThe instructions are printed in full; the excerpt above is shortened here for space. The three attachment tables are also abridged here: the command prints every row. source reads command line for an agent created with add.
#aegis ai agents add
Create an agent that has no file. The command line owns it from then on.
aegis ai agents add <slug> options| Option | Default | Meaning |
|---|---|---|
--name | slug | display name |
--description | "" | one line about the agent |
--kind | sub-agent | master, sub-agent or utility |
--model | "" (config default) | model slug |
--max-steps | 25 | provider hops one turn may make (1–200) |
--instructions-file | "" | read the instructions from this file |
--parallel | off | allow sub-agents and tools to run concurrently |
aegis ai agents add helper --name "Helper" --model deepseek-flashaegis ai agents add auditor --kind utility --max-steps 8 --instructions-file notes.md✔ helper: agent addedA taken slug, an unknown kind or an unknown model exits 1 with the reason; an unreadable --instructions-file prints ✖ cannot read the instructions: [Errno 2] No such file or directory: 'notes.md'.
#aegis ai agents edit
Change the fields that were passed on an agent the command line owns. Anything omitted keeps its value. An agent that comes from a file is refused, with the path to edit instead.
aegis ai agents edit <slug> options| Option | Default | Meaning |
|---|---|---|
--name | unchanged | display name |
--description | unchanged | one line about the agent |
--kind | unchanged | master, sub-agent or utility |
--model | unchanged | model slug |
--max-steps | unchanged | provider hops one turn may make |
--instructions-file | "" | replace the instructions from this file |
--parallel | unchanged | allow concurrency |
--no-parallel | unchanged | forbid concurrency |
aegis ai agents edit helper --max-steps 15aegis ai agents edit helper --no-parallel --model deepseek-v4-pro✔ helper: agent updatedPassing nothing that changes a field exits 1 with ✖ nothing to change.
#aegis ai agents remove
Destructive. The row is deleted. On a system agent the command refuses; on an agent created here the deletion is immediate and there is no undo.
Delete an agent the command line owns. Its attachment rows go with it. A file-owned agent cannot be removed here: remove the directory under storage/ai/agents/ and run aegis ai setup.
aegis ai agents remove <slug>| Argument | Default | Meaning |
|---|---|---|
slug | required | agent to delete |
aegis ai agents remove helperaegis ai agents remove auditor✔ helper: agent removed✖ this agent comes from /aegis/storage/ai/agents/aegis/agent.md; remove the file and run `aegis ai setup`#aegis ai agents tools
List the tools attached to an agent, with optional attachments and detachments in the same call. --add takes a pattern: shell.* for a whole pack, or one name such as files.read. The final table is always the state after the changes, so it doubles as a check.
aegis ai agents tools <slug> --add <pattern> --remove <name>| Option | Default | Meaning |
|---|---|---|
--add | none | attach every tool the pattern matches; repeatable |
--remove | none | detach this exact tool name; repeatable |
aegis ai agents tools aegisaegis ai agents tools aegis --add 'shell.*' --remove web.fetchtool pack status──────────── ───── ──────shell.ps shell activeshell.run shell activefiles.read files activeA pattern that matches nothing prints ⚠ nothing matched: shell.*; a name that was not attached prints ⚠ not attached: web.fetch. Both are warnings, and the command still exits 0.
#aegis ai agents skills
List the skills an agent carries, with the same --add/--remove shape as tools. --add accepts a slug (conventions) or a category pattern (aegis/*).
aegis ai agents skills <slug> --add <pattern> --remove <slug>| Option | Default | Meaning |
|---|---|---|
--add | none | attach every skill the pattern matches; repeatable |
--remove | none | detach this exact skill slug; repeatable |
aegis ai agents skills aegisaegis ai agents skills scout --add troubleshootingskill name category───────────────── ────────────────── ────────platform-overview Platform overview aegistroubleshooting Troubleshooting aegis#aegis ai agents subagents
List the agents one agent may delegate to, and change that list. Only an attached agent can be called with agents.call; recursion is capped at two levels by the engine.
aegis ai agents subagents <slug> --add <slug> --remove <slug>| Option | Default | Meaning |
|---|---|---|
--add | none | attach this agent as a sub-agent; repeatable |
--remove | none | detach this sub-agent; repeatable |
aegis ai agents subagents aegisaegis ai agents subagents helper --add scout --add aegisagent name kind───── ───── ─────────scout Scout sub-agent#Tools
A tool is a Python class with a ToolSpec. The catalogue row mirrors that spec: a sync writes it, and a row can disable a tool but never change what it does. Tools are grouped in packs (shell, files, aegis, …), which is also the unit a turn loads.
#aegis ai tools list
Print the tools grouped by pack, or one plain table when --pack names a pack. Columns are the tool name, whether it mutates the host, its status and its timeout.
aegis ai tools list --pack <pack> --all| Option | Default | Meaning |
|---|---|---|
--pack | "" (all packs) | only this pack; prints one ungrouped table |
--all | off | include disabled and archived tools |
aegis ai tools listaegis ai tools list --pack shelltool mutator status timeout──────────────── ─────── ────── ───────aegis/aegis.command active 120saegis.docs_read active 30sshell/shell.ps active 30sshell.run yes active 120sThe pack-filtered form:
tool mutator status timeout───────── ─────── ────── ───────shell.ps active 30sshell.run yes active 120s#aegis ai tools show
Print one tool as a key/value block, then its description, when to use it, and the parameter schema as JSON. declared says whether the module that defines the tool still exists in this build.
aegis ai tools show <name>| Argument | Default | Meaning |
|---|---|---|
name | required | tool name, for example files.read |
aegis ai tools show files.readaegis ai tools show shell.runname files.readpack filesstatus activemutator noconcurrency paralleltimeout 30sdeclared yesRead a text file from the project tree, with an optional line range. The path is relative to the project root.When: When you know which file holds the answer.[ { "name": "path", "type": "string", "description": "Path relative to the project root." }, { "name": "start", "type": "integer", "description": "First line, 1-based.", "default": 1 }]#aegis ai tools enable
Put a tool back in active state so agents that carry it are offered it again. The change survives the next sync.
aegis ai tools enable <name>| Argument | Default | Meaning |
|---|---|---|
name | required | tool name |
aegis ai tools enable shell.runaegis ai tools enable files.write✔ shell.run: active#aegis ai tools disable
Stop offering a tool to the model while keeping its row and its attachments. This is the safe way to remove a dangerous capability without editing any agent file. It is reversible with enable.
aegis ai tools disable <name>| Argument | Default | Meaning |
|---|---|---|
name | required | tool name |
aegis ai tools disable shell.runaegis ai tools disable files.write✔ shell.run: disabled#aegis ai tools sync
Write every tool declaration into ai.db. The status column is preserved, and a tool whose module disappeared is archived rather than deleted.
aegis ai tools sync| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis ai tools syncaegis ai tools sync && aegis ai tools list✔ 41 tools in 12 packsWhen a row was archived, the line ends with the count:
⚠ 1 tool(s) archived: their module is gone✔ 41 tools in 12 packs, 1 archived#Skills
A skill is a prompt block an agent carries. Skills that ship with the platform live as storage/ai/skills/<category>/<slug>/skill.md with a TOML header between +++ lines; those are read-only here. Skills created with add have no file and are owned by the command line.
#aegis ai skills list
Print the skills with their category, type, body size and status.
aegis ai skills list --category <name> --all| Option | Default | Meaning |
|---|---|---|
--category | "" (all) | only this category |
--all | off | include archived skills |
aegis ai skills listaegis ai skills list --category aegisslug name category type chars status───────────────── ──────────────────── ──────── ─────────── ───── ──────ai AI module aegis reference 6120 activebind BIND and DNS aegis reference 4821 activeconventions Project conventions aegis instruction 3890 activeplatform-overview Platform overview aegis reference 5210 activeThe valid types are instruction, prompt, reference, template, workflow and other.
#aegis ai skills show
Print one skill's metadata and then its body, unchanged.
aegis ai skills show <slug>| Argument | Default | Meaning |
|---|---|---|
slug | required | skill slug |
aegis ai skills show conventionsaegis ai skills show platform-overviewslug conventionsname Project conventionscategory aegistype instructiontags rules, style, processversion 1.0.0status activesource /aegis/storage/ai/skills/aegis/conventions/skill.md# ConventionsThese are not suggestions; a change that breaks one is sent back.## Code- Python 3.12. `X | None`, built-in generics, `from __future__ import annotations` where it helps.#aegis ai skills add
Create a skill that has no file. A body is required: pass it inline with --content or read it from a file with --file.
aegis ai skills add <slug> options| Option | Default | Meaning |
|---|---|---|
--name | slug | display name |
--category | "" | grouping label, for example aegis |
--description | "" | one line about the skill |
--type | instruction | one of the six skill types |
--file | "" | read the body from this file |
--content | "" | the body, inline |
aegis ai skills add house-style --name "House style" --file notes.mdaegis ai skills add on-call --category ops --content "Escalate to the on-call rota."✔ house-style: skill added (1840 chars)With neither --file nor --content:
✖ a skill needs a body: pass --file or --content#aegis ai skills edit
Change the fields that were passed on a skill the command line owns. There is no --category here: a skill's category is fixed at creation. A file-owned skill is refused with the path to edit.
aegis ai skills edit <slug> options| Option | Default | Meaning |
|---|---|---|
--name | unchanged | display name |
--description | unchanged | one line about the skill |
--type | unchanged | one of the six skill types |
--file | "" | replace the body from this file |
--content | "" | replace the body inline |
aegis ai skills edit house-style --file notes.mdaegis ai skills edit on-call --type workflow✔ house-style: skill updated#aegis ai skills remove
Destructive. The row is deleted, and there is no undo. A skill that comes from a file is refused: delete the directory and sync instead.
Delete a skill the command line owns.
aegis ai skills remove <slug>| Argument | Default | Meaning |
|---|---|---|
slug | required | skill to delete |
aegis ai skills remove house-styleaegis ai skills remove on-call✔ house-style: skill removed#aegis ai skills sync
Import every skill.md under storage/ai/skills into the catalogue. A changed file updates its row, an unchanged one is left alone, a file that disappeared archives its row. Rows with no file are never touched.
aegis ai skills sync --root <directory>| Option | Default | Meaning |
|---|---|---|
--root | storage/ai/skills | import from another directory instead |
aegis ai skills syncaegis ai skills sync --root /tmp/skills✔ 2 created, 1 updated, 7 unchanged, 0 archived#Chats
#aegis ai chat
Open a conversation in the plain terminal: a line in, a streamed answer out, a prompt again. It is a read-eval-print loop, not a full-screen application, so it works over any SSH session. The banner names the agent, the model and the chat; /help lists the commands below.
aegis ai chat --agent <slug> --chat <uuid> --model <slug> --no-stream --max-steps <n>| Option | Default | Meaning |
|---|---|---|
--agent | ai.default_agent (usually aegis) | agent for a new chat |
--chat | "" | continue this chat instead of opening one |
--model | the agent's model | model for a new chat |
--no-stream | off | one request per hop, no streamed text |
--max-steps | 0 | hops per turn; 0 means the agent's own limit |
--agent and --model only apply when the command opens a chat; with --chat they are ignored and the chat's own agent and model are used.
aegis ai chataegis ai chat --chat 629a26dc16ad4a8ea68240705cb60654aegis ai chat --agent aegis --model deepseek-flash --no-streamAegis chat · agent aegis · model deepseek-flashchat 629a26dc16ad4a8ea68240705cb60654/help for commands · Ctrl-D to leave› ce servicii sunt oprite? · Run aegis status 574msNu este oprit niciun serviciu: keeper, panel, pulse și bird rulează.1 step(s) · 1 tool(s) · 8142/126 tokens · $0.0018›An unknown chat exits 1:
✖ unknown chat: 629a26dcAn unknown agent exits 1 with a pointer to setup:
✖ unknown agent: helper; run `aegis ai setup`A turn that fails prints the message after ✖; a turn stopped by the operator prints ℹ stopped, and the transcript stays readable.
#The chat REPL
Lines starting with / are commands for the shell around the chat. Anything else is a prompt for the agent, in the same chat, until you leave. Every command prints its answer and returns to the prompt.
#/help
Print the command list.
/help| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/helpCommands /help this list /new start a new chat /sessions [n] list chats, or switch to one by number or UUID /chat the UUID of this chat /model [slug] show or change the model of this chat /context how full the window is /compact fold the older messages into a summary /tools what this agent can call /quit leave (Ctrl-D does the same)#/new
Start a new chat on the same agent and model. The old chat stays in the database; the banner prints the new UUID.
/new| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/newAegis chat · agent aegis · model deepseek-flashchat 6f1c0b2e9a7d4c0f8b3e5d6a1c2b3d4e/help for commands · Ctrl-D to leave#/sessions
List the last twenty chats, newest first, or switch to one by its list number or a UUID prefix. A switch reloads the agent, the model and the transcript.
/sessions n|prefix| Argument | Default | Meaning |
|---|---|---|
n / prefix | none (list only) | list number or UUID prefix to switch to |
/sessions/sessions 3/sessions 629a26dc# chat agent messages updated─ ──────── ───── ──────── ───────────────────1 6f1c0b2e aegis 12 2026-11-17 06:41:022 629a26dc aegis 48 2026-11-17 06:12:443 2b7e55aa scout 6 2026-11-16 22:07:19 /sessions <n> to switchℹ switched to 2b7e55aa8c1d4e0f9a6b5c4d3e2f1a0b✖ no session matches 99#/chat
Print the UUID of the open chat, which is the value --chat and the panel expect.
/chat| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/chat629a26dc16ad4a8ea68240705cb60654#/model
Show the model of the open chat, or change it for the rest of the conversation. The change is written to the chat row, so it survives a reconnect.
/model slug| Argument | Default | Meaning |
|---|---|---|
slug | none (show only) | model slug to switch to |
/model/model deepseek-v4-prodeepseek-flashℹ model: deepseek-v4-pro✖ unknown model: gpt-9#/context
Print how full the window is, how many messages a fold always keeps, and how much text the current summary holds.
/context| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/context24118 / 1000000 tokens (2.4%) · keep_last 6 · summary 0 chars#/compact
Fold the older messages now, with the model writing the summary. It keeps the last compact_keep_recent messages verbatim and stores the summary on the chat; the transcript rows are not rewritten.
/compact| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/compact/compactℹ folding 34 messages…ℹ summary 5120 chars · until message 18When there is nothing old enough to fold:
ℹ nothing older than the kept tail; no fold needed#/tools
Print what the open chat's agent can call, grouped by pack with a count per pack.
/tools| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/toolsaegis (6) aegis.command, aegis.docs_read, aegis.docs_search, aegis.info, aegis.services, aegis.tasksshell (2) shell.ps, shell.runA chat with no agent prints ℹ this chat has no agent; an agent with nothing attached prints ℹ no tool attached.
#/quit
Leave the chat. /exit and /q are accepted aliases, and Ctrl-D does the same.
/quit| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments |
/quit/exitNo output beyond the shell prompt returning.
#Keys
| Key | At the prompt | During a turn |
|---|---|---|
Enter | send the line | — |
Ctrl-D | leave the chat | — |
Ctrl-C | clear the line | mark the turn interrupted and return to the prompt |
Escape twice within 1.2 s | — | ask the turn to stop between hops |
↑ / ↓ | history, when the readline module is present | — |
A question from interact.* is printed inline; numbered options are offered when the tool declared them, and typing the number selects that option. The question is answered on the terminal, and the answer becomes the tool result.
#One-shot prompts
#aegis ai prompt
Run exactly one turn and print the answer. Without --chat it opens a chat and prints its UUID on the last line; with --chat it continues that conversation. Streaming is the default: text arrives as the provider writes it, tool calls print as they run, and the final line carries the chat and the counters.
prompt locks the interaction pack: a one-shot run cannot ask you a question. Use aegis ai chat when the agent may need an answer.
aegis ai prompt <text> --agent <slug> --chat <uuid> --model <slug> --no-stream --json --max-steps <n> --background| Option | Default | Meaning |
|---|---|---|
text | required | the prompt; several words are joined with spaces |
--agent | ai.default_agent | agent for a new chat |
--chat | "" | continue this chat |
--model | the agent's model | model for a new chat |
--no-stream | off | one request, print the final text once |
--json | off | print one JSON object and nothing while it runs |
--max-steps | 0 | hops for this turn; 0 means the agent's own |
--background | off | queue the turn for the daemon and return |
--agent and --model only apply when a new chat is opened; with --chat the existing chat's agent and model are used.
aegis ai prompt "ce servicii sunt oprite?" --agent aegisaegis ai prompt --chat 629a26dc16ad4a8ea68240705cb60654 "și câte sunt în total?"aegis ai prompt "spune ok" --no-streamaegis ai prompt --json "spune ok"Serviciile oprite sunt: niciunul. Keeper, panel, pulse și bird rulează.ℹ chat 629a26dc16ad4a8ea68240705cb60654 · 2 steps · 1 tools · 8142/126 tokens · $0.0018With --json, one object on stdout:
{"ok": true, "chat": "629a26dc16ad4a8ea68240705cb60654", "turn": 6, "status": "done", "content": "ok", "steps": 1, "tool_calls": 0, "input_tokens": 3937, "output_tokens": 2, "cost": 0.000592, "error": ""}aegis --json ai prompt … is the same as --json. In JSON mode a failed turn still prints the object; the exit code is 1.
An empty prompt exits 1 with ✖ nothing to ask. A missing key fails before anything is spent:
✖ no api key for deepseek; run `aegis ai providers set-key deepseek`Ctrl-C during the turn marks it interrupted, exactly like the chat.
#Queuing the turn
With --background the command stores a turn and returns at once; the aegis-ai daemon claims it. It prints the new turn id and the chat UUID:
aegis ai prompt --background "cât e ceasul?"✔ turn 42 queued for chat 629a26dc16ad4a8ea68240705cb60654With --json the same call emits:
{"ok": true, "turn": 42, "chat": "629a26dc16ad4a8ea68240705cb60654", "status": "queued"}Follow the turn with aegis ai jobs list, or read its row with aegis ai jobs show 42.
#Background work
A background turn is a row in ai_turns with status = 'queued'. The daemon claims turns with a conditional update — one per worker, up to [ai] max_turns — runs each with the same engine as a foreground prompt, and publishes every event on the Bird topic ai. A turn that needs an answer goes waiting until aegis ai answer fills the question or the interaction timeout expires.
#aegis ai jobs list
Print the most recent turns, newest first, with the chat (short UUID), agent, status, counters, cost and start time.
aegis ai jobs list --limit <n>| Option | Default | Meaning |
|---|---|---|
--limit | 20 | how many turns to print |
aegis ai jobs listaegis ai jobs list --limit 5id chat agent status steps tools cost started── ──────── ────── ────── ───── ───── ─────── ───────────────────42 629a26dc aegis done 3 4 $0.0041 2026-11-17 06:40:1241 6f1c0b2e scout done 1 2 $0.0007 2026-11-17 06:32:5540 2b7e55aa aegis failed 0 0 $0.0000 2026-11-17 06:20:03An empty queue prints ℹ no turn yet.
#aegis ai jobs show
Print one turn: its counters, its error, then the prompt (first 600 characters) and, when the turn is waiting, the questions nobody answered.
aegis ai jobs show <id>| Argument | Default | Meaning |
|---|---|---|
id | required | numeric turn id from jobs list |
aegis ai jobs show 42aegis ai jobs show 17turn 42chat 1183origin clistatus donesteps 3tools 4tokens 9120/310cost $0.0041error —care e starea serviciilor?question type uuid───────────────────────── ─────── ────────────────────────────────May I restart nginx? confirm a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0dAn unknown id prints ✖ unknown turn: 42 and exits 1.
#aegis ai jobs cancel
Destructive. A queued turn is marked
cancelledand will never run; a running turn is asked to stop between hops, so its partial transcript stays. Neither kills a process.
Drop a queued turn, or ask a running or waiting one to stop.
aegis ai jobs cancel <id>| Argument | Default | Meaning |
|---|---|---|
id | required | numeric turn id |
aegis ai jobs cancel 42aegis ai jobs cancel 17✔ turn 42: dropped from the queue✔ turn 17: stop requestedA finished turn cannot be cancelled:
✖ turn 12 is done, nothing to cancel#aegis ai answer
List the questions nobody answered, or answer one. Without a UUID it prints the pending table; with one it stores the text and the waiting worker continues.
aegis ai answer uuid --text <answer>| Argument | Default | Meaning |
|---|---|---|
uuid | "" (list only) | question UUID, or its numeric id |
--text | "" | the answer; asked for on the terminal when omitted |
aegis ai answeraegis ai answer a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d --text "yes"uuid type question asked──────────────────────────────── ─────── ──────────────────── ───────────────────a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0d confirm May I restart nginx? 2026-11-17 06:40:31✔ answered: a3f1c9d24b7e4a0f8c6d5e4b3a2f1c0dWithout a pending question the listing says ℹ no pending question. An unknown or already answered question exits 1:
✖ that question is answered#aegis ai daemon
Run the background worker in the foreground. The keeper starts it as the service aegis-ai; use this command to watch it, or to run it once by hand.
aegis ai daemon| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis ai daemonaegis keeper services1 turn(s) interrupted by the previous processready: 2 worker(s), poll 1.5sturn 42 done: 3 steps, 4 tools, $0.0041turn 43 failed: 0 steps, 0 tools, $0.0000 — HTTP 401The daemon takes an exclusive lock in run/ai.lock, writes run/ai.pid, and rewrites run/ai.heartbeat while it runs, so the keeper can tell a frozen process from a working one. A second copy logs already running (pid 802341) and exits 0. A turn left running by a dead process is marked interrupted at start — never resumed, because half its transcript already exists.
Set [ai] daemon = false (or ai.enabled = false) to keep this host out of the queue entirely; [ai] max_turns and [ai] poll tune the workers.
#Reading a turn's outcome
Every command that runs a turn reports the same statuses, and jobs list shows them in the status column:
| Status | Meaning |
|---|---|
queued | waiting for the daemon |
running | a worker holds it |
waiting | stopped on a question (interact.*) |
done | the model returned a final answer |
failed | a provider or tool error; error holds the message |
cancelled | the operator asked it to stop |
interrupted | Ctrl-C, or a dead process's turn recovered at daemon start |
max_steps | the hop limit was reached; stored as failed |
The footer of prompt and chat is the same shape everywhere, with the values of that turn:
ℹ chat 629a26dc16ad4a8ea68240705cb60654 · 2 steps · 1 tools · 8142/126 tokens · $0.0018#Configuration
All keys live under [ai] in config/ai.toml (the file is merged with every other config/*.toml by load_server()).
| Key | Default | Meaning |
|---|---|---|
default_agent | aegis | agent when a command names none |
default_provider | deepseek | provider used when a chat names none |
default_model | deepseek-flash | model for an agent without one |
max_turns | 2 | background turns run at once |
max_steps | 25 | provider hops one turn may make |
parallel_agents | 4 | concurrent sub-agents |
parallel_tools | 4 | concurrent tool calls |
toolbox | true | offer the loading gate instead of every schema |
shell_confirm | true | confirm a mutating tool before it runs |
interaction_timeout | 600 | seconds a turn waits for an answer |
request_timeout | 300 | seconds one provider request may take |
compact_auto | true | fold before the window fills |
compact_threshold | 0.80 | share of the window that triggers a fold |
compact_keep_recent | 6 | messages a fold always keeps verbatim |
compact_keep_tokens | 15000 | tokens of the tail the fold must not touch |
compact_buffer | 16000 | room kept free below the window |
daemon | true | run aegis-ai on this host |
enabled | true | switch the module off entirely |
Provider credentials live in [providers.<slug>]: name, driver, auth_type, api_url, api_key, is_default and status. The database row written by set-key wins over api_key here; a sync never copies the config key into the row, so clearing the row restores the fallback.
#Exit codes
| Code | When |
|---|---|
0 | the command did what it was asked, including a listing that found nothing |
1 | an unknown slug or id, a missing key, a refused edit, a failed prompt |
2 | the line itself was wrong: unknown command, missing argument |
130 | the root command was interrupted |
The commands themselves never ask "are you sure"; the destructive ones are marked above. The only prompts are the secret set-key reads, the answer answer reads when --text is omitted, and the questions a chat turn asks through the interact.* tools.