CLI reference

Manage documents and run searches from the terminal.

The CLI is a quick way to interact with Aether without writing any code. It's great for testing your setup, inserting a few documents, running a quick search, or checking what's in your store.

aether-py is bundled with the Python SDK — install it with pip install aether-ai.

Authentication

The CLI reads your API key from the AETHER_API_KEY environment variable, the same as the SDKs:

export AETHER_API_KEY="your-api-key"

Get a key from the Aether Dashboard.

Document management

Insert a document

Upload a file. The file is embedded and indexed automatically.

aether-py insert ./reports/q4-summary.pdf
aether-py insert ./data/notes.txt

Update a document

Replace the content of an existing document by its ID. Aether re-chunks, re-embeds, and re-indexes the new content.

aether-py update abc123 ./reports/q4-summary-v2.pdf

List documents

List all active (non-deleted) documents.

aether-py list

Get document metadata

Retrieve metadata for a specific document by its ID.

aether-py get abc123

Download a document

Download a stored document to a local path. Use -o to set the output location.

aether-py download abc123
aether-py download abc123 -o ./output/report.pdf

Delete a document

Soft-delete a document. The document is excluded from future queries but can be restored.

aether-py delete abc123

Restore a document

Bring a deleted document back into the active pool. It becomes searchable again immediately.

aether-py restore abc123

Search

Search your documents using natural language. Aether converts your query into a vector and finds the most semantically similar content — so searching for "deployment architecture" will also match documents about "infrastructure setup" even if those exact words aren't used.

Use -k to control how many results are returned.

aether-py search "distributed consensus protocols"
aether-py search "quarterly revenue" -k 10
aether-py search "deployment architecture" -k 3