Skip to content

cli.md

Latest commit

 

History

History
132 lines (76 loc) · 3.73 KB

cli.md

File metadata and controls

132 lines (76 loc) · 3.73 KB

CLI Reference

The cortexdb package exposes two equivalent binaries: cortex and cortexdb.

Global options

Option Description
--db, --path, --database Database directory. Defaults to CORTEXDB_PATH or .cortexdb.
--json Emit machine-readable JSON.
--help, -h Show help.
--version, -v Show package version.

Database paths reject .. traversal segments and null bytes.

Commands

init [path]

Create or open a file-backed database directory.

cortex init ./.cortexdb

remember [content..]

Store a memory from arguments or stdin.

Options: --kind, --namespace, --agent-id, --user-id, --tag/--tags, --metadata, --confidence, --importance, --trust, --visibility.

cortex --db ./.cortexdb remember "Release checklist requires smoke tests" --tag release --importance 0.9

recall [terms..]

Recall memories by query.

Options: --query/-q, --top-k/--limit, --include-untrusted.

cortex --db ./.cortexdb recall release checklist --top-k 5 --json

search [terms..]

Run text, semantic, or hybrid search.

Options: --query/-q, --mode, --top-k/--limit.

cortex --db ./.cortexdb search "release checklist" --mode hybrid

context [action] [terms..]

Pack model context. The supported action is pack.

Options: --query/-q, --budget/--max-tokens, --top-k, --format markdown|text|json|xml|message-array.

cortex --db ./.cortexdb context pack release checklist --budget 1200 --format markdown

stats

Show memory count, fact count, storage size, storage metadata, vector stats, text stats, graph stats, and temporal stats.

compact

Compact file-backed storage and report reclaimed space.

inspect <id>

Find and render a memory, fact, run, entity, relationship, task, goal, plan, or evaluation dataset by ID.

graph [action] [values..]

Actions: list, show, entity, upsert, create, link, neighbors, path, explain.

Common options: --name, --entity, --from, --to, --type, --depth, --metadata.

cortex --db ./.cortexdb graph entity --name payments-service --type service
cortex --db ./.cortexdb graph link --from payments-service --to ledger-db --type depends_on
cortex --db ./.cortexdb graph neighbors payments-service --depth 2

runs [action] [id]

Actions: list, start, create, get, inspect, finish, fail, timeline.

Options: --name, --agent-id, --status, --metadata, --output, --error, --limit.

tasks [action] [id]

Actions: list, create, get, inspect, claim, update, block, complete.

Options: --title, --description, --status, --priority, --assignee, --agent-id, --goal-id, --reason, --metadata, --limit.

facts [action] [id]

Actions: list, assert, create, get, inspect, update, retract, delete, remove.

Options: --subject, --predicate, --object, --status, --source, --confidence, --reason, --metadata, --include-inactive, --limit.

export [output]

Export database state as portable JSON to stdout or a file.

import <input>

Import database state from a JSON export file.

backup [output]

Create a snapshot backup and report its path and size.

doctor

Run health checks for path existence, storage open state, schema version, WAL counts, indexes, records, and storage size.

eval

Run retrieval evaluation from a dataset JSON file or list datasets when no dataset is provided.

Options: --dataset, --method hybrid|semantic|text|recall|context, --top-k/-k.

Exit codes

runCli() returns 0 on success and 1 on errors. Shell invocations follow the same convention.