Next: , Previous: , Up: The Command-Line Client   [Contents][Index]

9.3 Subcommand reference

Global options come before the subcommand name; subcommand options come after: 

ownsona [--config PATH] [--server URL] [--token TOKEN] [--json] <command> [...]

Run ownsona --help for top-level help, ownsona <command> --help for per-command help.

9.3.1 Common flags

--tags T1,T2,...

Comma-separated tags. Used by add, update, query (as a filter), import (default for line-format files), teach.

--limit N

Cap on returned rows. Used by query, search, list, prompt.

--dedup POLICY

One of insert, skip_if_near, ask. Default ask for add; skip_if_near for teach.

--expires-at, --last-confirmed-at

ISO 8601 timestamps on add and update.

9.3.2 add (remember)

ownsona add "My dog's name is Mochi." --tags family,pets

Output: Ok (id=42).

9.3.3 query (recall)

ownsona query "what is my dog's name"

Output: 

1 match
  [42] score=0.913  My dog's name is Mochi.
    tags: family pets
    at:   2026-05-16T12:00:00Z

9.3.4 search (text_search)

Plain substring search: 

ownsona search "Mochi"

9.3.5 list

Recent memories, newest first. --include-deleted also shows tombstones. 

ownsona list --limit 20

9.3.6 update (update_memory)

ownsona update 42 "My dog's name is Mochi and she's a Shiba Inu."

9.3.7 confirm

Refresh last_confirmed_at without rebuilding the embedding: 

ownsona confirm 42

9.3.8 forget

Soft-delete by default; --hard drops the row entirely. Pair with --reason or --replaced-by to leave a tombstone trail (rejected with --hard, since there’s no row left to attach the reason to). 

ownsona forget 42
ownsona forget 42 --reason "misremembered name" --replaced-by 99
ownsona forget 42 --hard

9.3.9 prompt (build_context_prompt)

ownsona prompt "What should I name my new dog?" --max-chars 1000

Pipe straight into another LLM: 

ownsona prompt "What should I name my new dog?" | some-llm-cli

9.3.10 import (remember_batch)

Bulk-load from a JSON array or a one-fact-per-line text file. The CLI chunks the input into batches of 200 (MAX_BATCH_SIZE). 

ownsona import facts.txt  --tags preferences --dedup skip_if_near
ownsona import facts.json --dedup skip_if_near

JSON file format: 

[
  {"text": "I live in Texas.",  "tags": ["personal"], "expires_at": "2030-01-01T00:00:00Z"},
  {"text": "I drive a Subaru.", "tags": ["personal"], "importance": 0.3}
]

Text-line file format: one fact per line, blank lines and lines starting with # are skipped.

Next: Output and JSON modes, Previous: Configuring the CLI, Up: The Command-Line Client   [Contents][Index]