Skip to content

cli.md

Latest commit

 

History

History
243 lines (170 loc) · 9.52 KB

cli.md

File metadata and controls

243 lines (170 loc) · 9.52 KB
title CLI reference
description Every `lazyagent` invocation flag, with syntax, defaults, and examples.
sidebar
order
1

This page documents the root lazyagent command — the one you run to monitor agents. Maintenance and search subcommands live alongside it:

Synopsis

lazyagent [--tui] [--gui] [--api] [--host ADDR]
          [--agent NAME] [--demo]
          [--version] [--help]

No flag at all is the most common invocation — it opens the TUI with every supported agent enabled.

Flags

Flag Type Default Summary
--tui bool auto Launch the terminal UI. Implicit when no other mode is set
--gui bool false Launch the macOS menu bar app (detaches)
--api bool false Start the HTTP API server
--host ADDR string 127.0.0.1:7421 API listen address (only relevant with --api)
--agent NAME string all Restrict monitoring to one agent
--demo bool false Use generated fake data instead of real sessions
--version bool false Print the version and exit
--help bool false Print usage and exit
--tray bool false Deprecated alias for --gui, kept for backwards compatibility

--tui

Explicitly open the terminal UI. Omitting it is the same as passing it unless another mode is specified:

lazyagent                    # implicit --tui
lazyagent --tui              # explicit, same result
lazyagent --api              # API only, no TUI
lazyagent --tui --api        # TUI in foreground, API in background

See Terminal UI for keybindings.

--gui

Launch the macOS menu bar app. The process detaches from your terminal immediately — the shell prompt returns, and the app appears in the menu bar.

lazyagent --gui              # menu bar only (detached)
lazyagent --gui --api        # menu bar + API in foreground
lazyagent --tui --gui --api  # everything (TUI foreground, tray and API in background)

On non-macOS systems --gui prints an error. See macOS GUI.

--api

Start the HTTP API server.

lazyagent --api              # default bind: 127.0.0.1:7421
lazyagent --api --host :8080 # custom port, localhost only
lazyagent --api --host 0.0.0.0:7421   # expose on the network

On the very first interactive run, --api prompts for a passphrase, saves it to ~/.config/lazyagent/config.json, and prints the derived bearer token to stderr once. On subsequent runs it does not print the token; use lazyagent passphrase --show when you explicitly need it. Set LAZYAGENT_API_PASSPHRASE in the environment to override the configured value (useful for CI / launchd).

If the chosen port is busy, the default bind falls back across 7421–7431; when --host is set, there is no fallback. Full reference: HTTP API.

--host ADDR

Override the API bind address. Accepts any Go net.Listen address:

Value Meaning
:7421 All interfaces, port 7421 (shorthand for 0.0.0.0:7421)
127.0.0.1:9000 Localhost, custom port
0.0.0.0:7421 All interfaces, default port (e.g. LAN exposure)

Ignored without --api.

--agent NAME

Restrict monitoring to one agent. Valid values:

Value Sessions included
claude Claude Code CLI and Desktop
pi pi coding agent
codex Codex CLI
amp Amp CLI
cursor Cursor IDE
opencode OpenCode
all Every enabled agent (default) 
lazyagent --agent claude     # only Claude
lazyagent --agent codex      # only Codex
lazyagent --agent all        # default — every agent

To disable agents permanently (rather than per-invocation), flip them in the agents map of your config.

--demo

Replace real session discovery with a curated fake dataset — useful for screenshots, demos, or debugging the UI without cluttering your actual agent history.

lazyagent --demo             # fake TUI
lazyagent --demo --gui       # fake tray app

Combinable with any interface flag.

--version

lazyagent --version

Prints the running version and, if a newer release is available on GitHub, a hint to update.

--help

lazyagent --help

Prints the full usage text, including short keybinding reference.

Subcommand dispatch

When the first positional argument is prune, compact, search, limits, or passphrase, lazyagent switches into subcommand mode — root-level flags are ignored and the subcommand parses its own set.

lazyagent prune --days 30          # prune subcommand
lazyagent compact --agent claude   # compact subcommand
lazyagent search --agent codex api # search subcommand
lazyagent limits --agent claude    # limits subcommand
lazyagent passphrase               # rotate the API passphrase
lazyagent --agent claude prune     # ❌ wrong: prune is not a flag value

See prune, compact, and limits for their flag tables.

search

search runs full-text search over local agent transcripts (Claude, Codex, pi, Amp) using an incremental SQLite FTS5 index under the user cache directory. Cursor and OpenCode are excluded because their history lives in third-party SQLite databases.

lazyagent search "race condition"
lazyagent search --agent codex "parser"
lazyagent search --reindex "config"

After printing results in an interactive terminal, search prompts for a result number; entering one opens that chat via the originating agent's resume command. Piped output stays non-interactive.

Full reference, including the index location, ranking, and resume commands: search.

limits

limits prints a one-shot snapshot of the 5-hour and weekly rate-limit windows for Claude Code and Codex, with a pace indicator that compares actual consumption to a perfectly linear pace (underutilizing / on track / overutilizing).

lazyagent limits                 # both agents
lazyagent limits --agent claude  # only Claude Code
lazyagent limits --agent codex   # only Codex

Claude data comes from /api/oauth/usage on api.anthropic.com — the same undocumented endpoint Claude Code's /status calls. Codex data is read from the latest rollout JSONL under ~/.codex/sessions/ (no network call).

Full reference, including disclaimers and token-resolution order: limits.

passphrase

passphrase sets or rotates the passphrase that protects the HTTP API. It runs without starting the server, so you can change credentials at any time and let any future lazyagent --api pick up the new value.

lazyagent passphrase             # interactive prompt and save
lazyagent passphrase --show      # print the bearer token for the current passphrase

passphrase (no flags) always prompts (double-entry confirmation), even if a passphrase is already configured — it's a rotation, not a setup. --show derives the token from the env var if LAZYAGENT_API_PASSPHRASE is set, otherwise from the configured value, without prompting or changing the passphrase.

--show writes the raw token to stdout (single line, no prefix) so it can be captured in a pipe: TOKEN=$(lazyagent passphrase --show). Diagnostics (passphrase source, missing-config hints) go to stderr. Other invocations do not print the token.

Restart any running lazyagent --api after rotating: the server reads the passphrase at startup, so it keeps using the old token until restarted.

Common invocations

# Terminal UI, all agents (the default)
lazyagent

# Terminal UI but only Claude
lazyagent --agent claude

# Menu bar app only
lazyagent --gui

# Menu bar app + HTTP API (ideal daily-driver combo on macOS)
lazyagent --gui --api

# HTTP API exposed on the LAN for a mobile client
lazyagent --api --host 0.0.0.0:7421

# Everything at once
lazyagent --tui --gui --api

# Demo mode for screenshots
lazyagent --demo --gui

# Search chat history
lazyagent search "api server"

Exit codes

Code Meaning
0 Normal exit
1 Runtime error (bind failure, invalid argument, IO error, …) — details printed to stderr

The maintenance subcommands define their own exit codes; see their respective pages.

Environment variables

Variable Effect
CLAUDE_CONFIG_DIR Alternate Claude home when claude_dirs is not set in the config. Must contain a projects/ subfolder
CLAUDE_CODE_OAUTH_TOKEN Override the OAuth token used by lazyagent limits for the Claude call. Bypasses the macOS keychain and the credentials file
XDG_CONFIG_HOME Overrides the default ~/.config base for ~/.config/lazyagent/
VISUAL Preferred GUI editor for o (TUI) / Open (GUI). See Editor support
EDITOR Fallback terminal editor when $VISUAL is unset
LAZYAGENT_DETACHED Internal marker set when the tray forks itself; do not set manually