CLI Reference

Powerful, scriptable access to the Aevum Encyclopedia. Search, fetch, export, and contribute to verified knowledge directly from your terminal.

v2.4.1 • ● Stable

Installation

Install ae-cli via your preferred package manager. Compatible with macOS, Linux, and Windows (via WSL).

Node.js / npm

npm install -g @aevum/cli

Python / pip

pip install aevum-cli

go install github.com/aevum/cli@latest

Homebrew

brew install aevum/tap/ae

bash
$ ae --version
Aevum CLI v2.4.1 (Built for Encyclopedia API v3)

Quick Start

Authenticate once, then start querying the knowledge graph instantly.

bash
$ ae auth login
# Opens browser for OAuth2. Token saved to ~/.aevum/config

$ ae search "quantum entanglement" --limit 5
# Returns structured JSON with titles, snippets, and graph IDs

Command Reference

`ae init`

Initializes a local Aevum project with configuration defaults and offline cache directory.

Usage: ae init [project-name] [options]

Flag	Type	Description
--template	string	Starter template: `research`, `education`, `api`
--cache-dir	string	Custom directory for offline article cache (default: `.aevum_cache`)

bash
$ ae init quantum-physics-research --template research
✓ Project scaffolded at ./quantum-physics-research
✓ Cache initialized (0 MB)

`ae search`

Queries the Aevum knowledge graph using semantic AI. Supports natural language, filters, and output formatting.

Usage: ae search <query> [options]

Flag	Type	Description
--lang	string	Filter results by language (e.g., `en`, `es`, `zh`)
--domain	string	Restrict to discipline: `science`, `history`, `tech`, `philosophy`
--output	string	Format: `json`, `table`, `markdown` (default: `json`)
--limit	integer	Max results (default: 10, max: 100)

bash
$ ae search "Renaissance art techniques" --domain history --output markdown
# Renders formatted markdown with inline citations

`ae fetch`

Retrieves full article content, metadata, and linked knowledge nodes by ID or slug.

Usage: ae fetch <id|slug> [options]

Flag	Type	Description
--include-graph	boolean	Attach related knowledge graph nodes
--cache	boolean	Save to local offline cache
--format	string	`html`, `markdown`, `pdf`, `json`

bash
$ ae fetch ae-quantum-computing-101 --include-graph --format pdf
✓ Downloaded: quantum-computing-101.pdf
✓ Graph nodes: 14 related concepts cached

`ae export`

Exports search results, cached articles, or knowledge graphs for offline analysis or LLM training.

Usage: ae export <source> [options]

Flag	Type	Description
--dest	string	Output directory or file path
--format	string	`jsonl`, `csv`, `wikitext`, `parquet`
--strip-metadata	boolean	Remove editorial tags and revision history

`ae sync`

Synchronizes local cache with the latest verified encyclopedia updates. Resolves conflicts using version vectors.

Usage: ae sync [options]

Flag	Type	Description
--dry-run	boolean	Preview changes without writing
--force	boolean	Overwrite local modifications
--scope	string	`all`, `recent`, `favorites`

Authentication

CLI authentication uses OAuth2 with refresh tokens. Tokens are stored encrypted in ~/.aevum/credentials.

bash
$ ae auth login      # Interactive browser flow
$ ae auth token --set ae_live_xK9...  # CI/CD environments
$ ae auth whoami    # Verify current session

For headless servers, set the AEVUM_TOKEN environment variable or use --token flag globally.

Configuration

Manage global and project-level settings. Configuration is stored in ~/.aevum/config.json or .aevumrc.

Usage: ae config [get|set|delete] <key> [value]

bash
$ ae config set default.lang en
$ ae config set api.timeout 15000
$ ae config get cache.enabled
true

Key	Default	Description
default.lang	`en`	Preferred content language
api.timeout	`10000`	Request timeout in ms
cache.enabled	`true`	Enable local offline caching
output.pager	`false`	Pipe long outputs to system pager

Environment Variables

Override config and auth behavior via environment variables. Useful for Docker and CI pipelines.

Variable	Description
AEVUM_TOKEN	API authentication token
AEVUM_API_BASE	Custom API endpoint (default: `https://api.aevum.enc`)
AEVUM_CACHE_DIR	Override default cache location
AEVUM_LOG_LEVEL	`debug`, `info`, `warn`, `error`
AEVUM_NO_COLOR	Disable terminal coloring (set to `1`)

Exit Codes

Code	Meaning
`0`	Success
`1`	General error / invalid command
`401`	Authentication failed or token expired
`429`	Rate limit exceeded (exponential backoff applied)
`500+`	Remote API error (retry with `--retry 3`)