Recordari CLI
Install, configure, and manage lifecycle hooks from the terminal.
The recordari CLI installs the agent skill, configures lifecycle hooks in your agent platform, and manages your API key — all in one tool. Download it from GitHub Releases or run the install script below.
Installation
# macOS / Linux
curl -fsSL https://pub-21464170f08f4747b42f28910795a7ad.r2.dev/install.sh | sh# Windows (PowerShell)
irm https://pub-21464170f08f4747b42f28910795a7ad.r2.dev/install.ps1 | iexAfter installing, verify with:
recordari version
recordari doctorCommands
| Command | What it does |
|---|---|
recordari init | Interactive wizard — API key, skill, hooks, doctor in one pass |
recordari init-hooks | Install lifecycle hooks directly (bypasses wizard) |
recordari config | Get or set local config values |
recordari options | View or update server-side hook behaviour settings |
recordari doctor | Diagnose skill and hook installation |
recordari hook | Run a single hook event (used by the installed hooks) |
recordari version | Print the installed version |
recordari init — interactive wizard
Running recordari init with no flags launches a guided 4-step wizard. It's the fastest way to go from a fresh install to a working Recordari setup.
recordari initWizard steps:
- API key — checks whether your API key is configured. If not, prompts you to paste one (saved to
~/.config/recordari/config). Get your key from the admin portal. - Skill file — fetches and writes the Recordari agent skill to
.claude/skills/recordari/SKILL.mdand adds the import line toCLAUDE.mdandAGENTS.md. - Lifecycle hooks — detects your agent platform (or uses
--platform) and installs hook entries into the platform's config. See Lifecycle hooks for what each hook does. - Doctor — runs
recordari doctorto confirm everything is wired up.
Each step asks for confirmation ([y/N]). You can accept all steps without prompting using --force.
Wizard flags:
| Flag | Effect |
|---|---|
--force | Accept all steps without prompts |
--dry-run | Preview every step without writing anything |
--endpoint URL | Override the skill fetch URL |
Legacy flags — these skip the wizard and run a specific operation directly:
| Flag | Effect |
|---|---|
--hooks | Install skill + hooks (no wizard) |
--global | Write hooks to global ~/.claude/settings.json (Claude Code only) |
--platform PLATFORM | Force a specific platform instead of auto-detecting |
--hooks-dir DIR | Install hook scripts to a custom directory |
recordari init-hooks — direct hook install
Installs lifecycle hooks without the wizard. Useful if you've already set up the skill manually or want to wire hooks independently.
recordari init-hooks
recordari init-hooks --platform cursor
recordari init-hooks --global # Claude Code: write to ~/.claude/settings.json
recordari init-hooks --force # Replace existing hook entriesFlags:
| Flag | Effect |
|---|---|
--platform PLATFORM | Target platform: claude-code, vscode-copilot, cursor, codex |
--global | Write to global ~/.claude/settings.json (Claude Code only) |
--force | Replace existing entries even if hooks are already present |
--hooks-dir DIR | Install hook scripts to a custom directory |
Platform auto-detection — if --platform is not set, the CLI detects the platform from the current directory:
.claude/present →claude-code.github/hooks/present →vscode-copilot.cursor/present →cursor- Default →
claude-code
Platform support:
| Platform | Config written | Hook events installed |
|---|---|---|
claude-code | .claude/settings.json | All 8 events |
codex | .claude/settings.json (same format) | All 8 events |
vscode-copilot | .github/hooks/{EventName}.json | All 8 events |
cursor | .cursor/hooks.json | 3 events (no PostCompact, no SubagentStart/Stop) |
Hook commands point directly to the recordari binary — no shell scripts or Python runtime required. The installer merges into your existing config without touching non-Recordari entries.
recordari config — local configuration
Reads and writes ~/.config/recordari/config. Environment variables always take precedence over the config file.
# Read
recordari config get api_key
recordari config get api_url
# Write
recordari config set api_key YOUR_API_KEY
recordari config set api_url https://api.recordar.ioSupported keys:
| Key | Env var override | Default |
|---|---|---|
api_key | RCD_API_KEY | — |
api_url | RCD_API_URL | https://api.recordar.io |
recordari options — hook behaviour settings
Views and updates your server-side hook behaviour preferences. Changes apply immediately across all your agent sessions.
# View all options and their current values
recordari options
# Set a value
recordari options set auto_recall true
recordari options set sweep_interval_turns 10
recordari options set session_orient_enabled falseAvailable options:
| Option | Type | Description |
|---|---|---|
session_orient_enabled | bool | Run orient() automatically at session start (SessionStart hook) |
auto_recall | bool | Inject relevant memories before each prompt (UserPromptSubmit hook) |
reinject_on_compact | bool | Re-run orient() after context compaction (PostCompact hook) |
pre_compact_enabled | bool | Inject compactor guidance before summarisation (PreCompact hook) |
sweep_interval_turns | int | Turns between filing prompts; 0 disables the stop-sweep entirely (Stop hook) |
subagent_orient_enabled | bool | Run orient() at sub-agent start, scoped to the parent session domain (SubagentStart hook) |
subagent_audit_enabled | bool | Run audit(orphans) during the stop-sweep (Stop hook) |
These settings are also editable in the admin portal under Settings.
recordari doctor — installation diagnostics
Checks your Recordari setup and reports ok, warn, or error for each item.
recordari doctor
recordari doctor --json # Machine-readable output
recordari doctor --endpoint URL # Override MCP server URLWhat it checks:
| Check | What it verifies |
|---|---|
binary | CLI version installed |
mcp-server | API reachable at api.recordar.io/doctor |
skill:present | .claude/skills/recordari/SKILL.md exists |
skill:version | Skill frontmatter has a version field |
skill:import-line | CLAUDE.md starts with @AGENTS.md |
hooks:claude-code (project) | Hooks in .claude/settings.json |
hooks:claude-code (global) | Hooks in ~/.claude/settings.json |
hooks:vscode-copilot | Hooks in .github/hooks/ |
hooks:cursor | Hooks in .cursor/hooks.json |
hooks:version | Hook commands match the installed binary version |
A warn on a hook check for a platform you don't use is expected. A warn on mcp-server usually means RCD_API_KEY is not set or the server is unreachable.
Lifecycle hooks
Hooks are small hook entries wired into your agent platform's event system. They run automatically at key moments in a session and inject Recordari context — orient output, filing prompts, compactor guidance — without any manual steps.
Hook events:
| Event slug | Platform event | What it does |
|---|---|---|
session-start | SessionStart | Calls orient() and injects the result + Layer 1 skill contract at session start |
stop-sweep | Stop | Prompts the agent to file decisions and findings when the sweep interval is reached |
pre-compact | PreCompact | Injects compactor guidance plus recent/stale context before the context is summarised |
post-compact | PostCompact | Re-runs orient() to restore context after compaction |
subagent-start | SubagentStart | Calls orient() scoped to the parent session's domain for sub-agents |
subagent-stop | SubagentStop | Increments the sub-agent completion counter for the parent stop-sweep |
user-prompt-submit | UserPromptSubmit | Nudges the agent to orient if it hasn't yet; optionally recalls relevant memories per prompt |
post-tool-use | PostToolUse | Counts remember/connect/revise tool calls for the stop-sweep summary |
The hooks use the recordari hook <slug> --platform <platform> command. They read credentials from RCD_API_KEY / RCD_API_URL env vars or ~/.config/recordari/config. Hook activity is logged to ~/.config/recordari/hook.log.
Disable a specific hook — toggle individual hooks in the admin portal under Settings or with recordari options set <option> false. There is no way to uninstall a single hook entry without editing the platform config directly; use --force to reinstall a clean set.
Troubleshooting
Hooks are installed but not firing — check that your agent platform recognises the hook format. Reload or restart the agent after installing hooks. On Claude Code, confirm with cat .claude/settings.json | grep hooks.
mcp-server: warn — not reachable — your api_key may not be configured. Run recordari config get api_key. If the key is missing, run recordari config set api_key YOUR_API_KEY.
skill:import-line: warn — CLAUDE.md does not start with @AGENTS.md. Re-run recordari init to repair the wiring.
Hook commands point to the wrong binary — if you move the recordari binary after installing hooks, doctor will report a stale path. Re-run recordari init-hooks --force to update the command paths.