Recalletta CLI

Installation

macOS / Linux (Homebrew)

brew tap recalletta/recalletta
brew install recalletta

Works on macOS (Intel & Apple Silicon) and Linux (x86_64).

Linux (Manual)

Download the latest binary from the releases page:

curl -L https://github.com/recalletta/homebrew-recalletta/releases/download/v0.6.1/recalletta-v0.6.1-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv recalletta /usr/local/bin/

Build from Source

git clone https://github.com/recalletta/recalletta
cd recalletta/cli
cargo build --release
sudo cp target/release/recalletta /usr/local/bin/

Quick Start

# Initialize (creates account or logs in, enables Claude Code hook)
recalletta init

# Verify hook is enabled
recalletta hook

# Start using Claude Code - sessions auto-save!
# Ask Claude to "recall" past sessions when you need context

Usage

The CLI uses smart argument detection:

# Search sessions (default behavior)
recalletta "authentication bug"

# Load session by ID (8+ hex chars auto-detected)
recalletta c658106c

# List recent sessions (no arguments)
recalletta

# List with date filter
recalletta --when today

Global Options

Option	Description
`-w, --when <FILTER>`	Date filter (see below)
`-n, --limit <N>`	Max results (default: 20)
`-j, --json`	Output as JSON
`-q, --quiet`	Suppress non-essential output
`--last`	Load most recent session
`--full`	Include full body in output
`--debug`	Enable debug logging
`--color <MODE>`	Color output: auto, always, never
`--api-url <URL>`	Override API URL
`--api-key <KEY>`	Override API key

Date Filters (--when)

Format	Example	Description
Keywords	`today`, `yesterday`	Shortcuts for common filters
Relative	`7d`, `2w`, `1m`, `1y`	Days, weeks, months, years ago
Exact date	`2025-01-15`	Specific date
Date range	`2025-01-01..01-31`	From..to range
Open range	`2025-01..` or `..2025-01-31`	From date or up to date

Commands

Search and List Sessions

Search is the default behavior - just pass your query:

# Search for text
recalletta "authentication bug"
recalletta "react hooks"

# Filter by date
recalletta "api" --when today
recalletta "refactor" --when yesterday
recalletta "bug" --when 7d
recalletta "feature" --when 2025-01..

# Limit results
recalletta "database" --limit 5

# List recent sessions (no query)
recalletta
recalletta --when today
recalletta --limit 50

# Output as JSON
recalletta "config" --json

Load Session Content

Pass a session ID (8+ hex chars) to load it automatically:

# Load by ID prefix (auto-detected)
recalletta 019abfa0
recalletta c658106c

# Load most recent session
recalletta --last

# Include full body
recalletta 019abfa0 --full

# Pipe to jq for processing
recalletta 019abfa0 | jq '.title'

info - Session Metadata

View summary and metadata without loading full content:

# Show session info
recalletta info 019abfa0

# Show only the title
recalletta info 019abfa0 --title

# Output as JSON
recalletta info 019abfa0 --json

tags - Browse and Search by Tags

# List all tags
recalletta tags

# Search sessions by tags (comma-separated)
recalletta tags "api,authentication"
recalletta tags "react,hooks"

upload - Upload Sessions

# Upload all new sessions from all agents
recalletta upload

# Upload from specific agent
recalletta upload claude
recalletta upload codex
recalletta upload gemini

# Upload a specific session by prefix
recalletta upload 019abfa0

# Upload a specific file
recalletta upload /path/to/transcript.md

delete - Delete Sessions

# Delete by ID (prompts for confirmation)
recalletta delete 019abfa0

# Delete without confirmation
recalletta delete 019abfa0 -y

hook - Claude Code Hook

Manage the hook that auto-saves sessions and injects context:

# Check hook status
recalletta hook

# Enable the hook
recalletta hook enable

# Disable the hook
recalletta hook disable

monitor - Background Process Monitor

Auto-upload sessions when agent processes exit:

# Monitor Codex CLI
recalletta monitor codex

# Monitor Gemini CLI
recalletta monitor gemini

# Monitor multiple agents
recalletta monitor codex gemini

keys - API Key Management

# List all API keys
recalletta keys

# Create a new key
recalletta keys create

# Create with custom name
recalletta keys create --name "laptop"

# Revoke a key
recalletta keys revoke rk_abc12

settings - Configuration

# Show all settings
recalletta settings

# Get a specific setting
recalletta settings debug

# Set a value (KEY=VALUE format)
recalletta settings debug=true
recalletta settings inject_summary=false

Authentication

# Show current user
recalletta auth

# Login
recalletta login

# Register new account
recalletta register

# Confirm email
recalletta confirm-email email@example.com --token TOKEN

init - First-time Setup

# Interactive setup
recalletta init

# Non-interactive
recalletta init myusername mypassword

stats - Usage Statistics

recalletta stats

Privacy Control

Disable recalletta for sensitive projects:

# Create opt-out marker in project root
touch .norecalletta

# Recalletta will skip this directory and all subdirectories

# Re-enable in a nested folder
touch subfolder/.yesrecalletta

Configuration

Configuration is stored in ~/.recalletta/config.json:

{
  "api_key": "rk_your_api_key_here",
  "api_url": "https://api.recalletta.ai/v1"
}

Environment Variables

Variable	Description
`RECALLETTA_API_KEY`	Override API key
`RECALLETTA_API_URL`	Override API URL
`RECALLETTA_DEBUG`	Enable debug mode (set to "1" or "true")

Workflow Examples

Daily Development

# Morning: Check yesterday's work
recalletta --when yesterday

# Search for context
recalletta "user authentication" --limit 5

# Load a relevant session
recalletta abc12345

# Work in Claude Code - sessions auto-save

Project Handoff

# Find sessions by tag
recalletta tags "project-alpha,api"

# Export as JSON
recalletta "project-alpha" --json > sessions.json

Debugging

# Search recent sessions for the error
recalletta "TypeError undefined" --when 30d

# Get session info
recalletta info 019abfa0

# Load full session
recalletta 019abfa0

Troubleshooting

Hook not working

recalletta hook
recalletta hook enable
cat ~/.claude/settings.json | grep recalletta

Sessions not uploading

recalletta auth
recalletta stats
recalletta --debug upload

Getting Help

recalletta --help
recalletta info --help
recalletta hook --help

For issues: GitHub Issues