Skip to main content

​
Command Reference

​
Authentication

​
login

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 (Experimental)

​
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

​
mcp

Run as an MCP server for Codex integration. 
npx agentlogs mcp
This command is meant to be called by Codex’s MCP server system, not manually. It:
  • Ensures the background service is running
  • Connects to the service to keep it alive
  • Exposes no tools or prompts (lifecycle management only)

​
service start

Start the background service. 
npx agentlogs service start
The service watches ~/.codex/sessions for transcript changes and uploads them automatically.

​
service stop

Stop the background service. 
npx agentlogs service stop

​
service status

Show background service status. 
npx agentlogs service status
Output: 
Service: running (PID: 12345)
Connections: 1
Watching: true
Uptime: 3600s
Last event: turn_complete (5s ago)

​
service logs

Tail the watcher event logs. 
npx agentlogs service logs
Shows recent file system events and turn completions. Press Ctrl+C to stop.

​
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:
OptionDescription
--helpShow help for a command
--versionShow CLI version
Example: 
# Get help for a specific command
npx agentlogs claudecode sync --help