Skip to content

cli.md

Latest commit

 

History

History
322 lines (229 loc) · 9.07 KB

cli.md

File metadata and controls

322 lines (229 loc) · 9.07 KB

CLI Reference

The ag command-line tool starts the Aegis server, launches MCP sessions, and provides quick session management.

The primary CLI command is ag. The legacy name aegis is kept as an alias for backward compatibility — both resolve to the same binary, so any existing scripts using aegis keep working.

Installation

npm install -g @onestepat4time/aegis
# or without a global install:
npx --package=@onestepat4time/aegis ag

Commands

ag init — Bootstrap a Project

Create .aegis/config.yaml with an API token, preferred base URL, optional BYO-LLM defaults, and dashboard settings.

ag init
ag init --yes            # Non-interactive defaults for CI
ag init --yes --force     # Overwrite existing config in non-interactive mode
ag init --list-templates
ag init --from-template code-reviewer

The interactive flow is idempotent: if .aegis/config.yaml already exists, ag init keeps it unless you confirm an overwrite. In --yes mode, existing config is preserved by default — use --force (or -f) to allow overwriting.

ag init also exposes the built-in starter gallery for Claude Code helpers:

  • code-reviewer (agent)
  • ci-runner (slash-command)
  • pr-reviewer (slash-command)
  • docs-writer (skill)

Scaffold one into the current directory, then validate it:

ag init --from-template docs-writer
ag doctor

ag run "prompt" — Zero-to-Session

Bootstrap config, start the server, create a session, and stream output — all in one command.

ag run "Build a REST API for managing tasks" --cwd .
ag run "Fix the auth bug"                     # Uses current directory
ag run "Refactor the utils" --no-stream       # Print curl commands instead of streaming
ag run "Debug the tests" --port 3000          # Custom server port
ag run "Fix CI" --yes                        # Non-interactive (CI-friendly)

What it does:

  1. Checks server health — is it running?
  2. If not: bootstraps config (if none exists) → starts server in background → waits up to 15s
  3. Creates a session with the prompt and working directory
  4. Streams session output to your terminal with role icons (👤 user, 🤖 assistant)
  5. Prints the dashboard URL for follow-up monitoring

If the server is already running, skips straight to session creation. Existing config is never overwritten (respects --force behavior from ag init).

Flags:

Flag Description
--cwd <path> Working directory (default: current directory)
--port <number> Server port override
--no-stream Don't stream output; print curl commands instead

ag — Start Server

Start the Aegis HTTP server (port 9100).

ag                     # Default: port 9100, 127.0.0.1
ag --port 3000         # Custom port
ag --host 0.0.0.0      # Bind to all interfaces
ag --json-logs         # Structured JSON logs (for CI/programmatic use)

Flags:

Flag Description
--port <number> HTTP server port override
--host <addr> Bind address
--json-logs Output structured JSON logs instead of human-friendly hints (for CI/programmatic use)

Requires AEGIS_AUTH_TOKEN for production use:

AEGIS_AUTH_TOKEN=secret ag

Environment variables:

Variable Default Description
AEGIS_BASE_URL http://127.0.0.1:9100 Preferred API origin for hooks + CLI clients
AEGIS_PORT 9100 HTTP server port
AEGIS_HOST 127.0.0.1 Bind address
AEGIS_AUTH_TOKEN (none) Bearer token (required for production)
AEGIS_DASHBOARD_ENABLED true Serve the bundled dashboard
AEGIS_STATE_DIR ~/.aegis Session state directory
AEGIS_MAX_SESSIONS (unlimited) Max concurrent sessions
AEGIS_IDLE_TIMEOUT_MS 600000 Idle timeout (10 min)
AEGIS_STALL_THRESHOLD_MS 120000 Stall threshold (2 min)

ag mcp — Start MCP Server

Start Aegis as an MCP stdio server for Claude Code, Cursor, Windsurf, and other MCP hosts.

ag mcp                    # Default: connects to localhost:9100
AEGIS_PORT=3000 ag mcp    # Custom API port

The MCP server wraps the REST API as tools — authenticate with:

AEGIS_AUTH_TOKEN=secret ag mcp

For Claude Code:

claude mcp add aegis -- ag mcp

For other MCP hosts (Cursor, Windsurf), see the Cursor integration or Windsurf integration.

ag auth migrate — Migrate Auth Token

Migrate a clientAuthToken from config.yaml to the canonical auth-token file (single source of truth).

ag auth migrate

What it does:

  1. Reads clientAuthToken from .aegis/config.yaml
  2. Writes the token to the canonical auth-token path
  3. Removes clientAuthToken from config.yaml
  4. Reports what was migrated

Run this after upgrading from a version that stored tokens in config. If the token is already in the canonical location, it reports that and exits cleanly.

ag list — List Sessions

List active and recent sessions.

ag list                        # All sessions
ag list --status running      # Filter by status

Flags:

Flag Description
--status <value> Filter sessions by status (e.g. running, idle, completed)

Displays each session as a compact row with truncated ID, status, and display name.

ag read <id> — Read Session Output

Fetch messages from a session.

ag read abc12345               # First 200 messages
ag read abc12345 --limit 50    # Last 50 messages
ag read abc12345 --page 2      # Paginate

Flags:

Flag Description
--page <number> Page number (default: 1)
--limit <number> Messages per page (default: 200)

ag kill <id> — Terminate a Session

Kill a running session by ID.

ag kill abc12345

Sends DELETE /v1/sessions/:id and confirms termination. Sessions in terminal states (killed, completed, crashed) return 404.

ag status — Server Health

Show server health and session summary.

ag status

Displays version, status, uptime, port, and active/total session counts.

ag tail <id> — Follow Session in Real-Time

Stream session events as they arrive (SSE).

ag tail abc12345

Connects to the session's event stream and prints output live. Press Ctrl+C to stop.

ag create "brief" — Quick Session

Create a session and send a brief in one command.

ag create "Build a login page with email and password" --cwd /path/to/project
ag create "Fix the failing tests"                     # Uses current directory

Options:

Flag Description
--cwd <dir> Working directory for the session
--port <port> Aegis API port (default: AEGIS_PORT or 9100)

This is a convenience wrapper that:

  1. Creates a session via POST /v1/sessions
  2. Sends the brief via POST /v1/sessions/:id/send
  3. Polls for status until delivered

Flags

Flag Description
--help, -h Show help
--version, -v Show version
--port <port> Server port (default: 9100)

ag doctor — Validate Starter Scaffolds

Run local health checks for built-in gallery files generated by ag init --from-template.

ag doctor

Today this command validates that any generated gallery files are present, readable, and still include the self-documenting sections expected by the template gallery.

Exit Codes

Code Meaning
0 Success
1 Error (server failed, session creation failed)

Examples

Start server with auth:

AEGIS_AUTH_TOKEN=my-secret ag --port 9100

Start with notification channels:

AEGIS_AUTH_TOKEN=secret \
AEGIS_TG_BOT_TOKEN=123456:ABC \
AEGIS_TG_GROUP_ID=-1001234567890 \
AEGIS_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx \
AEGIS_EMAIL_HOST=smtp.example.com \
AEGIS_EMAIL_USER=alerts@example.com \
AEGIS_EMAIL_PASS=app-password \
AEGIS_EMAIL_TO=ops@example.com \
ag

Quick session from project directory:

cd /path/to/project
AEGIS_AUTH_TOKEN=secret ag create "Review the code and suggest improvements"

Start MCP server for Claude Code:

AEGIS_AUTH_TOKEN=secret ag mcp

Quick Reference

ag                     Start HTTP server
ag init                Bootstrap .aegis/config.yaml
ag init --list-templates
ag init --from-template code-reviewer
ag run "prompt"        Zero-to-session (bootstrap + start + create + stream)
ag list                List sessions
ag read <id>           Read session output
ag kill <id>           Terminate a session
ag status              Server health + session summary
ag tail <id>           Follow session events in real-time
ag create "brief"      Create + send
ag doctor              Validate starter scaffolds
ag mcp                 Start MCP server
ag --port 3000         Custom port
ag --help              Show all options
ag --version           Show version

aegis remains available as an alias for every command above (e.g. aegis mcp still works).