Command Reference

Authentication

Authenticate with AgentLogs using device authorization.

npx agentlogs login <hostname>

Examples:

npx agentlogs login agentlogs.ai
npx agentlogs login localhost:3000

The hostname is required. The CLI opens a browser for authentication and stores your token locally for that host.

logout

Remove stored authentication credentials.

npx agentlogs logout [hostname]

With a hostname, logs out only from that host.
Without a hostname, logs out from all configured hosts.

status

Show current authentication status and account info.

npx agentlogs status

Output (example):

🔐 AgentLogs Authentication Status

agentlogs.ai (https://agentlogs.ai)
  ✅ Logged in
  👤 Example User
  📧 [email protected]

Upload

upload

Interactively browse and upload transcripts from any agent (Claude Code, Codex, OpenCode, Pi).

npx agentlogs upload [directory] [options]

Arguments:

directory - Optional. Filter to transcripts from this directory

Options:

-s, --source <source> - Filter by source: claude-code, codex, opencode, or pi
-l, --latest - Upload the most recent transcript without showing picker

Behavior:

Discovers transcripts from all installed agents
Shows an interactive picker to select a transcript
Displays time, source, directory, and preview for each transcript
Uploads the selected transcript

Examples:

# Interactive picker with all transcripts
npx agentlogs upload

# Only show transcripts from current directory
npx agentlogs upload .

# Only show Claude Code transcripts
npx agentlogs upload --source claude-code

# Upload most recent transcript without picker
npx agentlogs upload --latest

# Upload most recent from current directory
npx agentlogs upload . --latest

Claude Code

claudecode sync

Sync all local Claude Code transcripts to AgentLogs.

npx agentlogs claudecode sync [claudeDir]

Arguments:

claudeDir - Optional. Path to Claude data directory. Defaults to ~/.claude

Options:

--cwd <path> - Only upload transcripts from sessions in a specific working directory

Behavior:

Scans for transcript files in the Claude directory
Skips already-uploaded transcripts (deduplication via SHA256)
Respects your allow/deny settings

Example:

# Sync all transcripts
npx agentlogs claudecode sync

# Only sync transcripts from a specific project
npx agentlogs claudecode sync --cwd /path/to/my-project

claudecode upload

Upload a specific transcript file.

npx agentlogs claudecode upload <transcript>

Arguments:

transcript - Path to the JSONL transcript file

claudecode hook

Hook entry point for Claude Code integration. Called automatically by Claude Code hooks.

npx agentlogs claudecode hook

Reads hook data from stdin. This command is meant to be called from Claude Code’s hook system, not manually.

Codex

codex upload

Upload a Codex transcript file.

npx agentlogs codex upload <transcript>

Arguments:

transcript - Path to the JSONL transcript file

Example:

npx agentlogs codex upload ~/.codex/sessions/2025/01/25/session-abc123.jsonl

codex hook

Hook entry point for Codex integration. Called automatically by Codex hooks.

npx agentlogs@latest codex hook

Reads hook data from stdin. This command is meant to be called from Codex’s hook system, not manually.

codex install

Install the AgentLogs Codex hook integration into ~/.codex.

npx agentlogs codex install

This command:

Enables codex_hooks in ~/.codex/config.toml
Writes AgentLogs hook entries to ~/.codex/hooks.json
Prefers AGENTLOGS_CLI_PATH when set, otherwise runs npx -y agentlogs@latest codex hook
Captures transcripts only; git commit tracking hooks are not installed by default

OpenCode

opencode upload

Upload an OpenCode session.

npx agentlogs opencode upload <sessionId>

Arguments:

sessionId - The OpenCode session ID to upload

Sessions are read from ~/.local/share/opencode/storage/. Example:

npx agentlogs opencode upload ses_abc123def456

opencode hook

Hook entry point for OpenCode plugin integration. Called automatically by the OpenCode plugin.

npx agentlogs opencode hook

Reads hook data from stdin and outputs JSON response. This command handles:

tool.execute.before - Intercepts git commits to add transcript links
tool.execute.after - Tracks commit metadata (SHA, branch, title)
session.idle - Uploads the complete transcript

This command is meant to be called from the OpenCode plugin, not manually.

Pi

pi upload

Upload a Pi session transcript.

npx agentlogs pi upload [sessionIdOrPath]

Arguments:

sessionIdOrPath - Optional. Session ID or path to session file

Behavior:

With no argument: lists recent Pi sessions
With session ID: finds and uploads that session
With file path: uploads the specified JSONL file

Sessions are read from ~/.pi/agent/sessions/. Examples:

# List recent sessions
npx agentlogs pi upload

# Upload by session ID (partial match works)
npx agentlogs pi upload abc123

# Upload by file path
npx agentlogs pi upload ~/.pi/agent/sessions/--myproject--/2025-01-25_abc123.jsonl

pi hook

Hook entry point for Pi extension integration. Called automatically by the Pi extension.

npx agentlogs pi hook

Reads hook data from stdin and outputs JSON response. This command handles:

tool_call - Intercepts git commits to add transcript links
tool_result - Tracks commit metadata (SHA, branch, title)
agent_end - Uploads the transcript after each agent turn completes
session_shutdown - Uploads the complete transcript

This command is meant to be called from the Pi extension, not manually.

Settings

settings

View or modify repository settings.

npx agentlogs settings [options]

Options:

--mode <mode> - Set capture mode: denylist or allowlist
--json - Output settings as JSON

Example:

# View current settings
npx agentlogs settings

# Switch to allowlist mode
npx agentlogs settings --mode allowlist

allow

Allow a repository to be captured.

npx agentlogs allow <path> [options]

Arguments:

path - Path to the repository

Options:

--visibility <level> - Set visibility: private, team, or public

Example:

# Allow a repo with default visibility
npx agentlogs allow /path/to/repo

# Allow with explicit visibility
npx agentlogs allow /path/to/repo --visibility private

deny

Deny a repository from being captured.

npx agentlogs deny <path>

Arguments:

path - Path to the repository

Example:

npx agentlogs deny /path/to/secret-repo

Global Options

These options work with any command:

Option	Description
`--help`	Show help for a command
`--version`	Show CLI version

Example:

# Get help for a specific command
npx agentlogs claudecode sync --help

Introduction

Agents

CLI

Server

Commands

Command Reference

Authentication

logout

status

Upload

upload

Claude Code

claudecode sync

claudecode upload

claudecode hook

Codex

codex upload

codex hook

codex install

OpenCode

opencode upload

opencode hook

Pi

pi upload

pi hook

Settings

settings

allow

deny

Global Options

​Command Reference

​Authentication

​login

​logout

​status

​Upload

​upload

​Claude Code

​claudecode sync

​claudecode upload

​claudecode hook

​Codex

​codex upload

​codex hook

​codex install

​OpenCode

​opencode upload

​opencode hook

​Pi

​pi upload

​pi hook

​Settings

​settings

​allow

​deny

​Global Options

Command Reference

Authentication

login

logout

status

Upload

upload

Claude Code

claudecode sync

claudecode upload

claudecode hook

Codex

codex upload

codex hook

codex install

OpenCode

opencode upload

opencode hook

Pi

pi upload

pi hook

Settings

settings

allow

deny

Global Options