Agentrails CLI.

Set up the encrypted local archive, connect approved agents, run background capture, and search their history without opening the desktop app. S3-compatible storage setup and connection verification live in the desktop app today.

Quick start

Install, initialize, connect.

The CLI requires Node.js 22.13 or newer. Install the package globally, initialize the archive, then inspect the provider catalog before you connect anything.

TerminalNode.js 22.13+

npm install --global @agentrails/cli

agentrails init
agentrails providers catalog
agentrails providers connect io.agentrails.codex
agentrails service install

Connecting a provider can update its local configuration. Agentrails creates a backup and preserves unrelated hook entries. The desktop app asks for approval first. Running the CLIproviders connect command is the explicit authorization. Useagentrails providers setup <provider-id> to make the configuration change yourself.

Confirm the first capture

Finish a run in the connected agent, then ask Agentrails to reconcile history and process queued hook events. The thread list shows the provider, surface, title, and visible-message coverage.

TerminalLocal verification

agentrails sync
agentrails queue
agentrails threads
agentrails verify

Commands

The commands you will use.

agentrails init

Create the local archive and print its data directory.

agentrails providers list

Show installed provider packages and connection state.

agentrails providers catalog

List known agent surfaces and their capture modes.

agentrails providers connect io.agentrails.codex

Install the approved Codex completion hook and enable its provider.

agentrails providers setup <provider-id>

Print the exact configuration path and hook snippet for manual setup.

agentrails providers verify <provider-id>

Check that every required provider hook is present without changing the file.

agentrails sync

Reconcile documented local history and drain the capture queue.

agentrails threads

List archived threads with provider and coverage information.

agentrails search "deployment"

Search the redacted local full-text index.

agentrails export <thread-id> --format markdown

Write one thread as Markdown, JSONL, or a portable ZIP.

agentrails verify

Verify SQLite integrity plus encrypted raw captures and stored artifacts.

agentrails service install

Start the background archive service when you sign in.

agentrails service status

Check whether the background service is installed and running.

Import a provider export

Choose the provider package and the file explicitly. Imports are limited to 512 MiB and the selected source enters the encrypted archive before normalization.

ExampleOfficial ChatGPT export

agentrails providers import \
  io.agentrails.openai-export \
  conversations.zip

Local files

Know where the archive lives.

agentrails init prints the active data directory. SetAGENTRAILS_HOME before the first command to use another location. The desktop app shows the same path in Settings.

macOS~/Library/Application Support/Agentrails

AGENTRAILS_HOME

Linux$XDG_DATA_HOME/agentrails or ~/.local/share/agentrails

AGENTRAILS_HOME

Windows%LOCALAPPDATA%\Agentrails

AGENTRAILS_HOME

The directory contains the encrypted raw archive, local SQLite index, capture queue, provider state, exports, and the v0.1 archive key. Search data and pending queue files are local plaintext protected by filesystem permissions. Do not place this directory inside a general cloud-sync folder.

Capture sources

Documented inputs only.

Agentrails does not scrape signed-in web apps. Every provider declares its capture method and coverage. A provider without an approved source remains unsupported.

Official hooks

After completed work

Codex CLI, Claude Code, Cursor, Gemini CLI, Windsurf, Copilot CLI

Documented history

At startup and on your schedule

Codex CLI, Claude Code, Gemini CLI

Selected imports

Only when you pick a file

ChatGPT, Claude, Cursor, OpenCode, Cline, Aider, Continue, Roo

Cloud archive

Connect the bucket now. Transfer stays gated.

Choose Cloudflare R2, AWS S3, Backblaze B2, Wasabi, DigitalOcean Spaces, MinIO, or a custom S3-compatible endpoint. The desktop app stores the credential with operating-system protection and verifies the private bucket with a random 64 KiB write, read-back, byte comparison, and delete probe. The probe never contains transcript content.

Encrypted archive upload and clean-device restore remain disabled in v0.1 while recovery keys, encrypted manifests, durable retries, and restore tests are completed. Local capture, search, integrity checks, and exports do not depend on cloud storage.

Read the cloud archive setup

Run the app or read the privacy model.

Install Agentrails Privacy model