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>
recuerd0 memory show --workspace <id> <memory_id>
recuerd0 memory create --workspace <id> --title <title> --content <body|->
recuerd0 memory update --workspace <id> <memory_id> [--title <title>] [--content <body|->]
recuerd0 memory delete --workspace <id> <memory_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`)

version

Create new versions of existing memories.

usage
recuerd0 version create --workspace <id> <memory_id> --content <body|->
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

search

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

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

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

version

search

Output Format

Error output

Global Flags

Exit Codes

Product

Resources

Legal