CLI Reference

getting started

Installation

Homebrew (macOS / Linux)

shell
brew install maquina-app/homebrew-tap/recuerd0-cli

Debian / Ubuntu

shell
curl -fsSL https://pkg.recuerd0.ai/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/recuerd0.gpg
echo "deb [signed-by=/usr/share/keyrings/recuerd0.gpg] https://pkg.recuerd0.ai/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/recuerd0.list
sudo apt update && sudo apt install recuerd0-cli

Fedora / RHEL

shell
sudo dnf config-manager --add-repo https://pkg.recuerd0.ai/rpm/recuerd0.repo
sudo dnf install recuerd0-cli

Windows (scoop)

powershell
scoop bucket add recuerd0 https://github.com/maquina-app/scoop-bucket
scoop install recuerd0-cli

Go install

shell
go install github.com/maquina-app/recuerd0-cli@latest

From source

shell
git clone https://github.com/maquina-app/recuerd0-cli.git
cd recuerd0-cli
make install

getting started

Quick Start

Four commands to go from install to search.

shell
# 1. Add your account
recuerd0 account add personal --api-url https://your-server.com --token YOUR_TOKEN

# 2. List workspaces
recuerd0 workspace list

# 3. Create a memory
recuerd0 memory create --workspace 1 --title "Auth patterns" --content "# Auth\nUse Bearer tokens..."

# 4. Search across everything
recuerd0 search "authentication"

getting started

Configuration

Multi-account setup with local overrides per project.

Global config

Stored at ~/.config/recuerd0/config.yaml. Manages multiple accounts.

~/.config/recuerd0/config.yaml
default_account: personal
accounts:
  personal:
    api_url: https://recuerd0.example.com
    token: r0_live_abc123...
  work:
    api_url: https://memory.company.io
    token: r0_live_def456...

Project-local config

Place a .recuerd0.yaml in any project root to set defaults for that directory.

.recuerd0.yaml
account: work
workspace: 3

Resolution order

Higher priority wins.

Priority	Source	Example
1 (highest)	CLI flags	`--account work`
2	Environment variables	`RECUERD0_TOKEN=...`
3	Project-local config	`.recuerd0.yaml`
4 (lowest)	Global config	`~/.config/recuerd0/config.yaml`

commands

Commands

account

Manage server connections.

usage
recuerd0 account add <name> --api-url <url> --token <token>
recuerd0 account list
recuerd0 account remove <name>
recuerd0 account default <name>

Subcommand	Description
`add`	Register a new account with API URL and token
`list`	Show all configured accounts
`remove`	Delete an account from config
`default`	Set the default account

workspace

List and manage workspaces.

usage
recuerd0 workspace list
recuerd0 workspace show <id>
recuerd0 workspace create --name <name> [--description <desc>]
recuerd0 workspace update <id> --name <name>
recuerd0 workspace archive <id>
recuerd0 workspace unarchive <id>

Subcommand	Description
`list`	List all active workspaces
`show`	Show workspace details and memory count
`create`	Create a new workspace
`update`	Update workspace name or description
`archive`	Archive a workspace (read-only)
`unarchive`	Restore an archived workspace

memory

Create, read, update, and delete memories.

usage
recuerd0 memory list --workspace <id> [--category CAT]
recuerd0 memory show --workspace <id> <memory_id>
recuerd0 memory create --workspace <id> --title <title> --content <body|-> [--category CAT]
recuerd0 memory update --workspace <id> <memory_id> [--title <title>] [--content <body|->] [--category CAT]
recuerd0 memory delete --workspace <id> <memory_id>
recuerd0 memory link list <memory_id> [--workspace <id>]
recuerd0 memory link add <memory_id> --to <other_memory_id> [--workspace <id>]
recuerd0 memory link remove <memory_id> --to <other_memory_id> [--workspace <id>]

Use --content - to read from stdin. Pipe markdown files directly: cat notes.md | recuerd0 memory create --workspace 1 --title "Notes" --content -

Flag	Description
`--workspace`	Target workspace ID (required, or set in `.recuerd0.yaml`)
`--title`	Memory title
`--content`	Markdown body, or `-` for stdin
`--tags`	Comma-separated tags: `--tags "auth,rails,patterns"`
`--source`	Source identifier (e.g. `cli`, `claude-code`)
`--category`	One of `decision`, `discovery`, `preference`, `general` (defaults to `general`). See Categories.

memory read

Read just what you need from large memories — head, tail, an explicit line range, or grep matches with surrounding context. Avoids loading the full body when you only care about a slice.

usage
recuerd0 memory read head <memory_id> --lines 20 [--workspace <id>]
recuerd0 memory read tail <memory_id> --lines 20 [--workspace <id>]
recuerd0 memory read lines <memory_id> --start 40 --end 55 [--workspace <id>]
recuerd0 memory read grep <memory_id> "TODO" --context 2 [--workspace <id>]

Subcommand	Description
`head`	First `--lines N` lines of the memory body
`tail`	Last `--lines N` lines, computed from `total_lines`
`lines`	Explicit range from `--start` to `--end` (1-based, inclusive)
`grep`	Find a pattern and print each match with `--context`, `--before`, or `--after` lines

Pair memory read grep with memory read lines: grep first to find the line number, then fetch a window of context around it. This is much cheaper than memory show for long transcripts and docs.

Value	Label	Purpose
`decision`	Decision	Architecture choices, library picks, tradeoffs with stated reasoning
`discovery`	Discovery	Non-obvious findings — gotchas, root causes, patterns, library quirks
`preference`	Preference	User-stated rules ("always X", "never Y")
`general`	General	Catch-all and default

version

Create new versions of existing memories.

usage
recuerd0 version create --workspace <id> <memory_id> --content <body|-> [--category CAT]
recuerd0 version list --workspace <id> <memory_id>
recuerd0 version show --workspace <id> <version_id>

Subcommand	Description
`create`	Branch a new version from a memory. Omitted fields inherit from parent.
`list`	List all versions of a memory
`show`	Show a specific version with content

Memory Links

Memory links — also called "tunnels" — are undirected, unlabeled "see also" connections between two memories within the same account. They cross workspace boundaries, so a memory in your rails-app workspace can link to one in your mobile-app workspace. Use them to express that two memories cover the same topic without duplicating content.

usage
recuerd0 memory link list <memory_id> [--workspace <id>]
recuerd0 memory link add <memory_id> --to <other_memory_id> [--workspace <id>]
recuerd0 memory link remove <memory_id> --to <other_memory_id> [--workspace <id>]

Subcommand	Description
`list`	List all memories linked to `<memory_id>`, with each linked memory's workspace
`add`	Create an undirected link from `<memory_id>` to the memory id passed via `--to`
`remove`	Remove the link to the memory id passed via `--to`

example workflow
# 1. Find a related memory in another workspace
recuerd0 search "auth strategy"

# 2. Link the two memories
recuerd0 memory link add 42 --to 118 --workspace 1

# 3. Confirm the link is in place
recuerd0 memory link list 42 --workspace 1

Links are same-account only — cross-account links are rejected. memory link remove identifies the link by the other memory's id (passed via --to), not by a separate join row id, because links are undirected and stored once per pair.

search

Full-text search across all memories. Supports FTS5 operators.

usage
recuerd0 search <query> [--workspace <id>] [--category CAT]

examples
# Simple search
recuerd0 search "authentication"

# FTS5 operators
recuerd0 search "auth AND rails NOT devise"

# Scope to a workspace
recuerd0 search "deploy" --workspace 3

# Column filter
recuerd0 search "title:architecture"

reference

Output Format

All commands output JSON by default. Use --pretty for formatted output.

search output
{
  "query": "authentication",
  "total_results": 2,
  "results": [
    {
      "id": 12,
      "title": "Auth Patterns",
      "workspace": { "id": 1, "name": "Rails Project" },
      "snippet": "Bearer token authentication with..."
    }
  ]
}

Error output

error
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}

reference

Global Flags

Available on all commands.

Flag	Env Variable	Description
`--account`	`RECUERD0_ACCOUNT`	Account name to use
`--token`	`RECUERD0_TOKEN`	API token (overrides config)
`--api-url`	`RECUERD0_API_URL`	Server URL (overrides config)
`--workspace`	`RECUERD0_WORKSPACE`	Default workspace ID
`--verbose`		Show HTTP request/response details
`--pretty`		Pretty-print JSON output

reference

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments or usage
`3`	Configuration error (missing account, bad config file)
`4`	Authentication failed (401)
`5`	Permission denied (403)
`6`	Resource not found (404)
`7`	Validation error (422)
`8`	Rate limited (429)

Installation

Homebrew (macOS / Linux)

Debian / Ubuntu

Fedora / RHEL

Windows (scoop)

Go install

From source

Quick Start

Configuration

Global config

Project-local config

Resolution order

Commands

account

workspace

memory

memory read

Categories

version

Memory Links

search

Output Format

Error output

Global Flags

Exit Codes

Product

Resources

Legal