CLI Reference
Reference for the currently implemented aegis CLI commands and flags.
CLI Reference
The aegis binary is the user-facing CLI for local stack management, daemon lifecycle, agent and workflow operations, cluster-node actions, and status inspection.
This page documents the command surface implemented in aegis-orchestrator/cli/src. If you are looking for built-in MCP tools such as aegis.agent.create, use the Management Tools reference instead; those are not shell subcommands.
Global Flags
These flags are parsed at the top level and can be combined with subcommands where relevant:
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
--config <path> | AEGIS_CONFIG_PATH | auto-discovered | Path to the node configuration file. |
--host <host> | AEGIS_HOST | 127.0.0.1 | Host used for daemon HTTP API calls. |
--port <port> | AEGIS_PORT | 8088 | Port used for daemon HTTP API calls. |
--log-level <level> | AEGIS_LOG_LEVEL | info | Log verbosity: trace, debug, info, warn, error. |
--output <format> | — | text | Render supported command results as text, table, json, or yaml. |
--daemon | — | false | Run the process in daemon mode instead of executing a CLI subcommand. |
Output Formats
The CLI uses a shared output contract for commands that return a finite result set. Use json or yaml for automation, and text or table for terminal-oriented use.
Supported structured-output commands include agent, task, workflow, node, config, daemon, status, and update flows that return a bounded summary. Streaming commands such as agent logs, task logs, and workflow logs remain stream-oriented and do not use the generic --output renderer. aegis workflow logs now renders persisted workflow execution events and can tail the live event stream with --follow, while aegis.workflow.logs returns paginated execution events instead of a live stream.
aegis config generate is the exception to the global --output flag: it writes a file and uses --out <path> instead.
Top-Level Commands
| Command | Purpose |
|---|---|
aegis daemon | Manage the background daemon process. |
aegis task | Execute agents and inspect execution records. |
aegis node | Perform cluster node bootstrap and peer operations. |
aegis config | Show, validate, or generate config files. |
aegis agent | Deploy, inspect, remove, log, or generate agents. |
aegis workflow | Validate, deploy, run, inspect, signal, cancel, remove, and generate workflows. |
aegis update | Pull images, restart services, run migrations, and refresh built-ins. |
aegis init | Guided first-time setup wizard. |
aegis down | Stop the local Docker Compose stack. |
aegis up | Start the local stack, running aegis init automatically if needed. |
aegis restart | Restart local Docker Compose services. |
aegis status | Report local stack health or cluster health. |
aegis uninstall | Tear down the local stack and remove its working directory. |
Authentication
Manage authentication sessions and profiles.
aegis auth login
Authenticate with an AEGIS environment using the browser-based Device Authorization Grant.
aegis auth login [OPTIONS]| Flag | Default | Description |
|---|---|---|
--env <hostname> | dev.100monkeys.ai | Environment hostname. Auth URL is derived as https://auth.<env>. |
--non-interactive | — | Exit non-zero if not already authenticated (for CI/CD). |
Example:
aegis auth login --env prod.100monkeys.aiaegis auth logout
Revoke the current session and clear local credentials.
aegis auth logoutaegis auth status
Show the current authentication state.
aegis auth status [--output <text|json|yaml>]aegis auth switch
Switch to a different stored profile.
aegis auth switch <profile>aegis auth token
Print the current access key to stdout. Useful for scripting:
export AEGIS_KEY=$(aegis auth token)aegis daemon
Manage the daemon lifecycle.
aegis daemon start
Starts the daemon if it is not already running. The CLI re-execs itself with --daemon and detaches it into the background.
aegis daemon start
aegis daemon start --config /etc/aegis/config.yamlaegis daemon stop
Stops the running daemon.
aegis daemon stop
aegis daemon stop --force --timeout 10| Flag | Default | Description |
|---|---|---|
--force, -f | false | Force termination if graceful shutdown fails. |
--timeout <seconds>, -t | 30 | Graceful shutdown timeout in seconds. |
aegis daemon status
Checks whether the daemon is running and whether its HTTP health probe succeeds.
aegis daemon status
aegis daemon status --output jsonaegis daemon install
Installs the daemon as a system service.
aegis daemon install
aegis daemon install --binary-path /usr/local/bin/aegis --user aegisaegis daemon uninstall
Removes the system-service installation.
aegis daemon uninstallStack Lifecycle
aegis init
Runs the guided setup wizard. It prepares stack files, configures the node, starts Docker Compose services, verifies health, and can optionally load smoke-test agents. The wizard now defers database migrations to aegis update after the daemon is running.
aegis init
aegis init --yes
aegis init --dir ~/.aegis --tag latest| Flag | Default | Description |
|---|---|---|
--yes | false | Accept defaults and skip interactive prompts. |
--manual | false | Print prerequisite instructions instead of auto-installing them. |
--dir <path> | ~/.aegis | Working directory for stack files. |
--host <host> | 127.0.0.1 | Host used for post-start health checks. |
--port <port> | 8088 | Port used for post-start health checks. |
--tag <tag> | binary version | Image tag for AEGIS-owned Docker images. |
aegis up
Starts the local stack. If the stack directory does not exist yet, this command runs aegis init automatically first.
aegis up
aegis up --profile temporal
aegis up --tag latest| Flag | Default | Description |
|---|---|---|
--dir <path> | ~/.aegis | Stack working directory. |
--host <host> | 127.0.0.1 | Host shown after startup and used by aegis init fallback. |
--port <port> | 8088 | Port shown after startup and used by aegis init fallback. |
--yes | false | Non-interactive defaults if aegis init is triggered automatically. |
--tag <tag> | config or binary version | Image tag to refresh into the stack before startup. |
--profile <name> | all services | Start only services in the selected Compose profile when the stack already exists. |
aegis down
Stops the local Docker Compose stack.
aegis down
aegis down --profile temporal
aegis down --volumes --yes| Flag | Default | Description |
|---|---|---|
--dir <path> | ~/.aegis | Stack working directory. |
--profile <name> | all services | Stop only services in the selected Compose profile. |
--volumes | false | Remove named volumes as part of teardown. |
--yes, -y | false | Skip the destructive-action confirmation prompt. |
aegis restart
Restarts the local Docker Compose services.
aegis restart
aegis restart --profile temporalaegis update
Refreshes the stack: pull images, restart services, run database migrations, and optionally re-deploy built-in agents and workflows.
aegis update
aegis update --dry-run
aegis update --skip-pull --skip-restart --skip-migrations
aegis update --output json| Flag | Default | Description |
|---|---|---|
--dir <path> | ~/.aegis | Stack working directory. |
--skip-pull | false | Skip docker compose pull. |
--skip-restart | false | Skip service restart. |
--skip-migrations | false | Skip database migrations. |
--skip-builtins | false | Skip built-in agent/workflow refresh. |
--dry-run | false | Preview actions without making changes. |
--tag <tag> | from config or binary version | Override the image tag used during refresh. |
aegis status
Reports health for the local stack by default. With --cluster, it queries the cluster controller for peer status and probes each node's orchestrator health.
aegis status
aegis status --cluster
aegis status --output json| Flag | Default | Description |
|---|---|---|
--dir <path> | ~/.aegis | Stack working directory used for local status checks. |
--cluster | false | Report cluster node health instead of local Compose status. |
aegis uninstall
Stops the local stack, removes volumes, and deletes the working directory.
aegis uninstall
aegis uninstall --yesaegis uninstall removes the local stack data directory.
aegis daemon uninstall only removes the daemon service registration.
aegis agent
aegis agent list
Lists deployed agents.
aegis agent list
aegis agent list --output jsonaegis agent deploy <manifest>
Deploys an agent manifest. By default this fails if an agent with the same name and version already exists; use --force to overwrite that exact pair.
aegis agent deploy ./agent.yaml
aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml --force
aegis agent deploy ./agent.yaml --output json| Flag | Default | Description |
|---|---|---|
--validate-only | false | Parse and validate without deploying. |
--force | false | Overwrite an existing agent with the same name and version. |
aegis agent show <AGENT_ID>
Prints the stored manifest as YAML by default, or JSON when --output json is used. This subcommand expects a UUID.
aegis agent show a1b2c3d4-0000-0000-0000-000000000001aegis agent remove <AGENT_ID>
Removes a deployed agent by UUID.
aegis agent remove a1b2c3d4-0000-0000-0000-000000000001aegis agent logs <AGENT_ID_OR_NAME>
Streams logs for an agent. The CLI accepts either a UUID or an agent name and resolves names through the daemon.
aegis agent logs python-coder
aegis agent logs a1b2c3d4-0000-0000-0000-000000000001 --follow
aegis agent logs python-coder --errors
aegis agent logs python-coder --verbose| Flag | Default | Description |
|---|---|---|
--follow, -f | false | Tail log output. |
--errors, -e | false | Show only error entries. |
--verbose, -v | false | Include verbose log output such as prompt details. |
aegis agent generate --input <text>
Runs the built-in agent generator flow and deploys the generated manifest.
Generated manifests are persisted under .aegis/generated/agents/ (or the configured AEGIS base dir)
and the command reports that artifact root alongside the execution id.
aegis agent generate --input "Create an agent that reviews pull requests for security issues."
aegis agent generate --input "Create a SQL migration reviewer agent" --follow| Flag | Default | Description |
|---|---|---|
--input <text>, -i | required | Natural-language intent for the generator. |
--follow, -f | false | Stream generator execution logs. |
aegis task
aegis task execute <AGENT>
Starts an execution for an agent. <AGENT> may be a UUID, a deployed agent name, or a path to a manifest file. If you pass a manifest path, the CLI deploys it first and then executes it.
aegis task execute python-coder
aegis task execute ./agent.yaml
aegis task execute python-coder --input '{"task": "Write a primality check."}'
aegis task execute python-coder --context '{"repo_url":"https://github.com/example/service","branch":"main"}'
aegis task execute python-coder --input @input.json --follow
aegis task execute python-coder --input @input.json --context @context.yaml --follow
aegis task execute python-coder --input @input.json --output json| Flag | Default | Description |
|---|---|---|
--input <value>, -i | empty object | Inline JSON/YAML, @file, or a plain string. |
--context <dict> | none | Context override dictionary as inline JSON/YAML or @file. Must deserialize to an object. |
--wait, -w | false | Block until the execution completes. |
--follow, -f | false | Stream execution logs. |
--context injects top-level execution variables for that run only. The value must be a JSON or YAML object. Reserved built-in execution keys are rejected by the orchestrator.
aegis task status <EXECUTION_ID>
Shows current execution status. Use --output json for automation.
aegis task status a1b2c3d4-1111-0000-0000-000000000001
aegis task status a1b2c3d4-1111-0000-0000-000000000001 --output jsonaegis task logs <EXECUTION_ID>
Streams or prints execution logs. Use --follow for live tailing in the CLI; use aegis.task.logs in MCP when you need paginated retrieval instead of a live stream.
aegis task logs a1b2c3d4-1111-0000-0000-000000000001
aegis task logs a1b2c3d4-1111-0000-0000-000000000001 --follow
aegis task logs a1b2c3d4-1111-0000-0000-000000000001 --errors-only
aegis task logs a1b2c3d4-1111-0000-0000-000000000001 --verboseaegis task cancel <EXECUTION_ID>
Cancels a running execution.
aegis task cancel a1b2c3d4-1111-0000-0000-000000000001
aegis task cancel a1b2c3d4-1111-0000-0000-000000000001 --forceThe CLI accepts --force, but the current daemon path cancels through the standard execution-cancel API rather than a separate force-kill path.
aegis task remove <EXECUTION_ID>
Removes an execution record.
aegis task remove a1b2c3d4-1111-0000-0000-000000000001aegis task list
Lists recent executions. Use --output json for machine parsing.
aegis task list
aegis task list --agent-id a1b2c3d4-0000-0000-0000-000000000001
aegis task list --limit 50
aegis task list --output tableaegis workflow
aegis workflow validate <file>
Validates a workflow manifest locally.
aegis workflow validate ./pipeline.yamlaegis workflow deploy <file>
Deploys a workflow through the daemon after local parsing. By default this fails if a workflow with the same name and version already exists; use --force to overwrite that exact pair.
aegis workflow deploy ./pipeline.yaml
aegis workflow deploy ./pipeline.yaml --force
aegis workflow deploy ./pipeline.yaml --output json| Flag | Default | Description |
|---|---|---|
--force | false | Overwrite an existing workflow with the same name and version. |
aegis workflow run <name>
Runs a registered workflow.
aegis workflow run dev-pipeline
aegis workflow run dev-pipeline --input '{"task": "..."}'
aegis workflow run dev-pipeline --input @input.yaml
aegis workflow run dev-pipeline --blackboard '{"review_threshold":0.9,"deploy_env":"staging"}'
aegis workflow run dev-pipeline --blackboard @blackboard.yaml
aegis workflow run dev-pipeline --param branch=main --param env=staging --follow
aegis workflow run dev-pipeline --wait
aegis workflow run dev-pipeline --input @input.yaml --output json| Flag | Default | Description |
|---|---|---|
--input <json>, -i | empty object | Workflow input as inline JSON/YAML or @file. Must deserialize to an object. |
--param <key=value>, -p | none | Individual workflow input values merged into the input object. Values are parsed as JSON when possible, otherwise treated as strings. |
--blackboard <dict> | none | Startup blackboard override dictionary as inline JSON/YAML or @file. Must deserialize to an object. |
--follow, -f | false | Stream workflow logs after the execution starts. |
--wait, -w | false | Block until the workflow execution completes. |
--blackboard merges on top of spec.context for that execution. Reserved workflow keys, including workflow, are rejected. The merged Blackboard becomes the live template context inside the Temporal worker and is forwarded into downstream Agent-state execution context.
aegis workflow list
Lists registered workflows.
aegis workflow list
aegis workflow list --long
aegis workflow list --label team=platform
aegis workflow list --output jsonaegis workflow executions list
Lists recent workflow executions. The workflow filter accepts either a workflow UUID or a workflow name, and the long view resolves the associated workflow metadata when available.
aegis workflow executions list
aegis workflow executions list --workflow-id a1b2c3d4-0000-0000-0000-000000000001
aegis workflow executions list --limit 50 --long
aegis workflow executions list --output jsonaegis workflow executions get <EXECUTION_ID>
Shows the current status, blackboard, and execution metadata for a single workflow run.
aegis workflow executions get a1b2c3d4-2222-0000-0000-000000000001
aegis workflow executions get a1b2c3d4-2222-0000-0000-000000000001 --output jsonaegis workflow signal <EXECUTION_ID>
Sends a workflow signal to a waiting human state or other signal handler in the execution.
aegis workflow signal a1b2c3d4-2222-0000-0000-000000000001 --response approved| Flag | Default | Description |
|---|---|---|
--response <text> | required | Signal payload forwarded to the workflow execution. |
aegis workflow cancel <EXECUTION_ID>
Cancels a running workflow execution.
aegis workflow cancel a1b2c3d4-2222-0000-0000-000000000001aegis workflow remove <EXECUTION_ID>
Removes a workflow execution record.
aegis workflow remove a1b2c3d4-2222-0000-0000-000000000001aegis workflow describe <name>
Prints a workflow definition. Use --output yaml or --output json for structured exports.
aegis workflow describe dev-pipeline
aegis workflow describe dev-pipeline --output yaml
aegis workflow describe dev-pipeline --output jsonaegis workflow logs <EXECUTION_ID>
Prints or streams workflow execution logs from the persisted workflow event stream.
Use --follow to tail live events, --transitions to focus on state changes, and --verbose
to include resolved workflow and execution metadata.
aegis workflow logs a1b2c3d4-2222-0000-0000-000000000001
aegis workflow logs a1b2c3d4-2222-0000-0000-000000000001 --follow
aegis workflow logs a1b2c3d4-2222-0000-0000-000000000001 --transitions
aegis workflow logs a1b2c3d4-2222-0000-0000-000000000001 --verboseaegis workflow delete <name>
Deletes a workflow from the registry.
aegis workflow delete dev-pipeline
aegis workflow delete dev-pipeline --yesaegis workflow generate --input <text>
Runs the built-in workflow generator flow and deploys the resulting workflow.
Generated workflow manifests are persisted under .aegis/generated/workflows/; if the workflow flow
creates missing agents, those manifests are persisted under .aegis/generated/agents/.
aegis workflow generate --input "Create a CI/CD workflow: build, test, and deploy a Rust service."
aegis workflow generate --input "Create a human-approval gated release workflow" --followaegis node
Use these commands for multi-node bootstrap and peer inspection.
aegis node init
Generates the node identity Ed25519 keypair at the configured keypair path.
aegis node init
aegis node init --devThe current implementation parses --dev but does not change the generated output; treat it as reserved for future development defaults.
aegis node join <endpoint>
Runs the controller attestation and challenge handshake.
aegis node join https://aegis-controller.internal:50056aegis node leave
This command name exists, but the current single-node baseline returns an error instead of performing deregistration.
aegis node leaveaegis node peers
Lists cluster peers known to the configured controller. Use --output json for automation.
aegis node peers
aegis node peers --output jsonNo CLI filters are currently implemented for this command.
aegis config
aegis config show
Prints the resolved configuration and can also show discovery paths. Use --output yaml or --output json for structured output.
aegis config show
aegis config show --paths
aegis config show --output yamlaegis config validate [file]
Validates a configuration file. If no file is provided, the CLI uses normal config discovery.
aegis config validate
aegis config validate ./my-config.yaml
aegis config validate --output jsonaegis config generate
Generates a sample config file.
aegis config generate
aegis config generate --out /etc/aegis/config.yaml
aegis config generate --examples| Flag | Default | Description |
|---|---|---|
--out <path>, -o | ./aegis-config.yaml | Output path. |
--examples | false | Use the annotated template with example values. |
Exit Codes
The CLI does not currently publish a stable command-by-command exit code contract beyond standard success/failure process behavior. For automation, prefer structured output and treat non-zero exit status as failure.
Node Configuration Reference
Complete specification for the NodeConfig YAML format (v1.0) — schema, field definitions, credential resolution, model alias system, and example configurations.
CLI Capability Matrix
Current CLI command coverage, MCP tool equivalents, and API-only surfaces in the AEGIS orchestrator.