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

# CLI Reference

> Complete reference for the Aegis Memory command-line interface

# CLI Reference

Complete reference for the Aegis Memory command-line interface.

## Installation

```bash theme={null}
pip install aegis-memory
```

## Configuration

### `aegis init`

Top-level setup wizard with lightweight framework detection (LangChain/CrewAI) and config bootstrap.

```bash theme={null}
aegis init              # Interactive wizard
aegis init -y           # Non-interactive defaults
```

### `aegis new`

Generate starter boilerplate from templates.

```bash theme={null}
aegis new customer-support
aegis new customer-support -o ./examples
```

### `aegis explore`

Interactive memory browser from your terminal.

```bash theme={null}
aegis explore
aegis explore -q "login failures" -k 10
```

### `aegis config init`

Interactive first-run setup.

```bash theme={null}
aegis config init          # Interactive
aegis config init -y       # Use defaults (non-interactive)
```

### `aegis config show`

Display current configuration.

```bash theme={null}
aegis config show
```

### `aegis config set`

Set a configuration value.

```bash theme={null}
aegis config set output.format json
aegis config set profiles.local.api_url http://localhost:8000
```

## Server Status

### `aegis status`

Check server health and connection.

```bash theme={null}
aegis status           # Pretty output
aegis status -j        # JSON output
aegis status -q        # Quiet (exit code only)
```

**Exit codes:**

* `0` - Server healthy
* `1` - Server unhealthy
* `2` - Connection failed

### `aegis stats`

Show namespace statistics.

```bash theme={null}
aegis stats                    # Default namespace
aegis stats -n production      # Specific namespace
aegis stats -a executor        # Filter by agent
```

## Memory Operations

### `aegis add`

Add a memory.

```bash theme={null}
aegis add "Memory content"                    # Basic
aegis add "Strategy" -t strategy -s global    # Strategy with global scope
aegis add -f ./insight.txt -t reflection      # From file
echo "Piped" | aegis add                      # From stdin
```

**Options:**

| Flag           | Short | Description                                      |
| -------------- | ----- | ------------------------------------------------ |
| `--agent`      | `-a`  | Agent ID                                         |
| `--user`       | `-u`  | User ID                                          |
| `--namespace`  | `-n`  | Namespace                                        |
| `--scope`      | `-s`  | Scope: `agent-private`, `agent-shared`, `global` |
| `--type`       | `-t`  | Type: `standard`, `strategy`, `reflection`       |
| `--share-with` |       | Agent IDs to share with                          |
| `--metadata`   | `-m`  | JSON metadata                                    |

### `aegis query`

Semantic search for memories.

```bash theme={null}
aegis query "search text"                     # Basic search
aegis query "patterns" -t strategy -k 5       # Filter by type
aegis query "task" -x planner,coordinator     # Cross-agent query
aegis query "test" --ids-only                 # IDs only for scripting
```

**Options:**

| Flag            | Short | Description                     |
| --------------- | ----- | ------------------------------- |
| `--top-k`       | `-k`  | Number of results (default: 10) |
| `--min-score`   |       | Minimum similarity score        |
| `--type`        | `-t`  | Filter by memory type           |
| `--cross-agent` | `-x`  | Query across these agents       |
| `--full`        |       | Show full content               |

### `aegis get`

Get a single memory by ID.

```bash theme={null}
aegis get 7f3a8b2c1d4e                        # Pretty output
aegis get 7f3a8b2c1d4e -j                     # JSON output
aegis get 7f3a8b2c1d4e --content-only         # Content only
```

### `aegis update`

Update a memory's content, metadata, and/or trust level. Changing content re-scans it
through the security pipeline and recomputes its embedding (and integrity hash, if
enabled). Metadata is **merged**, not replaced.

```bash theme={null}
aegis update 7f3a8b2c1d4e "Corrected content"     # New content (arg)
aegis update 7f3a8b2c1d4e -f ./fixed.txt          # New content from file
echo "Piped content" | aegis update 7f3a8b2c1d4e  # New content from stdin
aegis update 7f3a8b2c1d4e -m '{"reviewed": true}' # Merge metadata
aegis update 7f3a8b2c1d4e --trust-level privileged
```

**Options:**

| Flag            | Short | Description                                                                  |
| --------------- | ----- | ---------------------------------------------------------------------------- |
| `--metadata`    | `-m`  | JSON metadata to merge                                                       |
| `--trust-level` |       | New trust level (`untrusted`, `unknown`, `internal`, `privileged`, `system`) |
| `--file`        | `-f`  | Read new content from file                                                   |
| `--json`        | `-j`  | JSON output                                                                  |

<Note>At least one of new content, `--metadata`, or `--trust-level` must be provided.</Note>

### `aegis delete`

Delete a memory.

```bash theme={null}
aegis delete 7f3a8b2c1d4e                     # With confirmation
aegis delete 7f3a8b2c1d4e -f                  # Force (no confirmation)
```

## Voting

### `aegis vote`

Vote on memory usefulness.

```bash theme={null}
aegis vote <id> helpful                       # Vote helpful
aegis vote <id> harmful -c "Caused bug"       # Vote harmful with context
```

**Options:**

| Flag        | Short | Description             |
| ----------- | ----- | ----------------------- |
| `--voter`   | `-v`  | Voting agent ID         |
| `--context` | `-c`  | Why this vote           |
| `--task`    | `-t`  | Related task/feature ID |

## Playbook

### `aegis playbook`

Query proven strategies and reflections.

```bash theme={null}
aegis playbook "error handling"               # Search playbook
aegis playbook "API" -t strategy -e 0.5       # Only high-rated strategies
```

**Options:**

| Flag                  | Short | Description                       |
| --------------------- | ----- | --------------------------------- |
| `--top-k`             | `-k`  | Number of results (default: 20)   |
| `--min-effectiveness` | `-e`  | Minimum effectiveness score       |
| `--type`              | `-t`  | `strategy`, `reflection`, or both |

## Session Progress

### `aegis progress create`

Create a new session.

```bash theme={null}
aegis progress create build-api -a executor
aegis progress create feature-x -s "Building feature X" -t 5
```

### `aegis progress update`

Update session progress.

```bash theme={null}
aegis progress update build-api -c auth -c routing
aegis progress update build-api -i api-client
aegis progress update build-api -b "payments:Waiting for API keys"
```

### `aegis progress show`

Show session details.

```bash theme={null}
aegis progress show build-dashboard
```

## Feature Tracking

### `aegis features create`

Create a feature.

```bash theme={null}
aegis features create user-auth \
    -d "User authentication with JWT" \
    -c auth \
    -t "Can login" \
    -t "Can logout"
```

### `aegis features verify`

Mark feature as passing.

```bash theme={null}
aegis features verify user-auth --by qa-agent
```

### `aegis features fail`

Mark feature as failed.

```bash theme={null}
aegis features fail 2fa-totp -r "TOTP validation fails"
```

## Data Management

### `aegis export`

Export memories to file.

```bash theme={null}
aegis export > backup.jsonl                   # To stdout
aegis export -o backup.jsonl                  # To file
aegis export -n prod -f json -o prod.json     # JSON format
```

### `aegis import`

Import memories from file.

```bash theme={null}
aegis import backup.jsonl                     # Import from file
aegis import backup.jsonl -n staging          # Override namespace
aegis import backup.jsonl --dry-run           # Validate only
```

## Maintenance

### `aegis prune`

Archive stale memories via the temporal-decay sweep — soft-deprecates memories whose
relevance score falls below the threshold. This is manual, CLI-triggered pruning; OSS
has no hosted scheduled policy, so run it on your own schedule (e.g. a cron job).

```bash theme={null}
aegis prune --dry-run                         # Preview count only
aegis prune                                   # Archive in default namespace
aegis prune -n research --threshold 0.2       # Higher cutoff in a namespace
```

**Options:**

| Flag          | Short | Description                                    |
| ------------- | ----- | ---------------------------------------------- |
| `--namespace` | `-n`  | Namespace to sweep                             |
| `--threshold` | `-t`  | Relevance-score cutoff, 0.0–1.0 (default: 0.1) |
| `--dry-run`   |       | Preview count without modifying rows           |
| `--json`      | `-j`  | JSON output                                    |

## Security Analysis

These commands are **standalone and server-free** — they run offline static analysis
and a local scan, and need no running server or API key.

### `aegis inspect`

Inspect an agent project for unsafe memory flows. Writes results to `aegis-out/`
(including `findings.sarif` for GitHub code scanning). Suppress an accepted sink with an
inline `# aegis: ignore` comment.

```bash theme={null}
aegis inspect .                               # Inspect current directory
aegis inspect ./agent --framework langgraph   # Force a sink adapter
aegis inspect . --ci --max-risk 60            # CI mode: non-zero exit on breach
```

**Options:**

| Flag                | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `--framework`       | Force a sink adapter (e.g. `langgraph`). Auto-detect by default. |
| `--baseline`        | Also inspect this path and use its risk score as the "before"    |
| `--ci`              | CI mode: machine output + non-zero exit on breach                |
| `--max-risk`        | CI risk-score threshold for a non-zero exit (default: 60)        |
| `--emit-cases`      | Also write `aegis-out/cases/cases.json`                          |
| `--ingest-verdicts` | Fold `aegis-out/cases/verdicts.json` back into the report        |

### `aegis replay`

Replay a built-in attack against the project using the real scanner, showing the
with/without-Aegis outcome.

```bash theme={null}
aegis replay .                                # Replay memory-poisoning demo
aegis replay . --attack memory-poisoning
```

**Options:**

| Flag       | Description                                              |
| ---------- | -------------------------------------------------------- |
| `--attack` | Built-in attack to replay (currently `memory-poisoning`) |

## Environment Variables

| Variable          | Description                |
| ----------------- | -------------------------- |
| `AEGIS_API_KEY`   | API key (highest priority) |
| `AEGIS_API_URL`   | Server URL                 |
| `AEGIS_PROFILE`   | Active profile             |
| `AEGIS_NAMESPACE` | Default namespace          |
| `AEGIS_AGENT_ID`  | Default agent ID           |

## Exit Codes

| Code | Meaning              |
| ---- | -------------------- |
| 0    | Success              |
| 1    | General error        |
| 2    | Connection error     |
| 3    | Authentication error |
| 4    | Not found            |
| 5    | Validation error     |