CLI Reference¶

Complete reference for all agentwatch commands.

Synopsis¶

agentwatch [command] [options]
agentwatch [--text | --json | --png] [options]

Global Options¶

Option	Description
`--version`	Show version and exit
`--version-json`	Show version as JSON and exit
`--help`, `-h`	Show help message

Commands¶

Service Management¶

start¶

Start the agentwatch daemon.

agentwatch start [options]

Option	Description
`-f`, `--foreground`	Run in foreground (don't daemonize)

Examples:

agentwatch start          # Start in background
agentwatch start -f       # Start in foreground (for debugging)

stop¶

Stop the agentwatch daemon. This is a cold stop: any live web-viewer logins are dropped, so the next start requires a fresh login. The Cloudflare tunnel is also torn down.

agentwatch stop

restart¶

Restart the daemon in place, preserving continuity. Unlike a stop followed by a start, restart is a deliberate, targeted operation that:

keeps you logged in to the web viewer (live logins are snapshotted and restored by the incoming daemon), and
hands off the Cloudflare tunnel to the new daemon instead of dropping it, so remote/web connections survive.

Prefer restart for routine restarts (after a code or config change). Use stop + start only when you specifically want a clean slate — e.g. forcing re-authentication. A crash or reboot behaves like stop + start: you log in fresh. Login continuity is bounded by the normal 24h session expiry; it is never extended by a restart.

agentwatch restart

status¶

Show daemon status and all monitored sessions.

agentwatch status [options]

Option	Description
`--config FILE`	Config file path

Output:

Daemon status (running/stopped)
Tunnel URL (if configured)
List of all sessions with program/state

Configuration¶

setup¶

Interactive setup wizard.

agentwatch setup [options]

Option	Description
`--token TOKEN`	Device token (skip prompt)
`--yes`	Non-interactive with defaults
`--start`	Start daemon after setup
`--strict`	CI mode: fail fast on errors

Examples:

agentwatch setup                              # Interactive
agentwatch setup --token TOKEN --yes --start  # Non-interactive
agentwatch setup --token TOKEN --strict       # CI/automation

config¶

Configuration management.

agentwatch config show
agentwatch config set <key> <value>

Subcommands:

Subcommand	Description
`show`	Show current configuration
`set token VALUE`	Set device token

Examples:

agentwatch config show
agentwatch config set token aw_abc123...

tunnels¶

List available tunnels.

agentwatch tunnels [options]

Option	Description
`--config FILE`	Config file path

Capture¶

One-Shot Capture¶

Capture terminal without daemon (requires tmux session).

agentwatch [options]

Option	Description
`--text`, `--txt`	Output full terminal text
`--json`	Output JSON with detection
`--png`	Output PNG screenshot
(none)	One-line status output

Examples:

agentwatch                    # One-line status
agentwatch --text             # Full terminal content
agentwatch --json             # JSON with detection results
agentwatch --png > snap.png   # Save PNG screenshot

capture¶

Capture a specific session from the daemon.

agentwatch capture <session> [options]

Argument	Description
`session`	Session name to capture

Option	Description
`--text`, `--txt`	Full terminal text
`--json`	JSON with detection
`--png`	PNG screenshot

Examples:

agentwatch capture coding                 # One-line status
agentwatch capture coding --text          # Full terminal
agentwatch capture coding --png > s.png   # Screenshot

Logging¶

logs¶

Extract and display daemon logs.

agentwatch logs [target] [options]

Argument	Description
`target`	Session, viewer, or session/viewer pair

Option	Description
`--list`	List all sessions and viewers
`-f`, `--tail`	Follow logs in real-time
`-n`, `--last N`	Show last N entries
`-c`, `--captures`	Include capture file contents
`--captures-only`	Show only captures
`--no-lifecycle`	Skip session lifecycle info
`--log FILE`	Custom log file path

Target formats:

SESSION - All logs for session
SESSION/VIEWER - Specific session+viewer pair
/VIEWER - All logs for viewer

Examples:

agentwatch logs --list              # List all sessions/viewers
agentwatch logs coding              # Logs for "coding" session
agentwatch logs coding/pig          # Logs for session+viewer pair
agentwatch logs coding --tail       # Follow logs
agentwatch logs coding -n 50        # Last 50 entries
agentwatch logs coding --captures   # Include capture contents

Updates¶

update¶

Check for and install updates.

agentwatch update [options]

Option	Description
`--check`	Check only, don't install

Examples:

agentwatch update          # Update to latest
agentwatch update --check  # Check without installing

rollback¶

Restore previous version from backup.

agentwatch rollback

Sessions¶

session¶

Create and manage coding sessions through the daemon. Each subcommand talks to the daemon's dual-auth /api endpoints (session cookie or the Bearer token at ~/.config/agentwatch/tokens/api). All subcommands accept --json for machine-readable output.

agentwatch session <subcommand> [options]

Subcommand	Description
`new --dir DIR`	Create a session. Options: `--agent claude_code\\|codex\\|shell`, `--name NAME`, `--task "..."`, `--permission-mode MODE` (agent-aware: claude_code → `default\\|acceptEdits\\|plan\\|bypassPermissions`; codex → `auto\\|read-only\\|full-access`; ignored for shell)
`respond NAME`	Send input. `--keys` (answer a prompt with keystrokes) or `--message "..."` (type text and submit, same as `tell`)
`tell NAME`	Send a message to a session; sugar for `respond --message`
`show NAME`	Show one session's status and common actions
`capture NAME`	Capture the session's terminal
`parse NAME`	Parse session output (`--verbose` for full detail)
`status [NAME]`	Show status for one session or all
`list`	List all sessions
`wait NAME`	Block until the session needs attention (`--timeout S`)
`wait-any NAME...`	Block until any listed session needs attention (`--timeout S`)
`send NAME`	Send raw terminal input: `--text`, `--enter`, `--key`, or `--ctrl`
`key NAME`	Send one named key; use `--list` to show key names
`scroll NAME`	Scroll copy-mode up/down or exit copy-mode
`resize NAME`	Resize terminal dimensions with `--cols` and `--rows`
`upload NAME`	Upload a file into the session's current working directory
`ls NAME`	List files in the session's project directory
`read NAME`	Read a file from the session's project directory (`--out FILE` for binary output)
`share NAME`	Share a file into the session inbox for the web viewer
`github NAME`	Print the GitHub repo link for the session's working directory
`vscode NAME`	Print the VS Code Web deep link for the session (opens its workdir)
`inbox NAME`	Push text to the session inbox, list inbox items, or clear the inbox
`clipboard NAME`	Deprecated alias of `inbox`
`exit NAME`	Ask the agent to exit gracefully
`terminate NAME`	Kill the session (`--force`)

Examples:

# Spawn a Claude Code session on a task
agentwatch session new --dir ~/myproject --task "Add a healthcheck endpoint"

# Drive a session on a remote host over SSH (no per-agent config needed)
ssh HOST agentwatch session new --dir ~/myproject --task "..."

# Coordinate several sessions
agentwatch session wait-any featA featB --timeout 300
agentwatch session respond featA --keys 1

Uninstall¶

uninstall¶

Remove agentwatch.

agentwatch uninstall [options]

Option	Description
`--purge`	Also remove config, tokens, and cache
`-y`, `--yes`	Skip confirmation prompt

Examples:

agentwatch uninstall           # Keep config
agentwatch uninstall --purge   # Remove everything

Debugging¶

auth-test¶

Test OS authentication (debugging).

agentwatch auth-test [username]

Argument	Description
`username`	Username to test (default: current user)

shell-hook¶

Output or install shell hook for automatic Claude restart.

agentwatch shell-hook [options]

Option	Description
`--bash`	Output bash hook
`--zsh`	Output zsh hook
`--fish`	Output fish hook
`--install`	Install hook to shell config
`--check`	Check if hook is installed

Legacy Options¶

These options are available on the main command for backward compatibility:

Option	Description
`--daemon`	Run in daemon mode (prefer `start`)
`--config FILE`	Config file path
`--generate-config`	Print default config to stdout
`--capture DIR`	Continuous capture to directory
`--interval N`	Capture interval in seconds
`--duration N`	Duration in seconds (0=forever)
`--no-clean`	Don't clean capture directory
`--login-link`	Generate magic login link

Exit Codes¶

Code	Meaning
0	Success
1	General error
2	Invalid arguments

Environment Variables¶

Variable	Description
`AGENT_WATCH_SOCKET`	tmux socket path
`AGENT_WATCH_TARGET`	tmux pane target (e.g., `session:0.0`)
`AGENT_WATCH_COLS`	Capture width (default: 80)
`AGENT_WATCH_ROWS`	Capture height (default: 72)
`AGENT_WATCH_FORMAT`	Output format (json/text/png)
`AGENTWATCH_TOKEN`	Device token override

Configuration File¶

Default location: ~/.config/agentwatch/config.yaml

See Configuration Reference for full details.

Files¶

Path	Description
`~/.local/bin/agentwatch`	Executable
`~/.config/agentwatch/config.yaml`	Configuration
`~/.config/agentwatch/tokens/api`	API token
`~/.config/agentwatch/tokens/device`	Device token
`~/.cache/agentwatch/daemon.log`	Daemon log
`~/.cache/agentwatch/daemon.pid`	PID file