xa.cli¶

Command-line interface for xa.

Exposes subcommands via cw: list, info, history, spawn, resume, kill, serve, sync, pick, gen-secret, revive, and the archive group (list, log, forensics).

Entry point: xa (see [project.scripts] in pyproject.toml).

Functions

`archive_forensics_cmd`(archive_id)	Print rich forensics for an archived session as JSON.
`archive_list_cmd`([limit, json_out])	List archived sessions (`created` events, newest first).
`archive_log_cmd`(archive_id[, tail_kb])	Print the pane log for an archived session.
`gen_secret_cmd`([length])	Print a cryptographically strong random hex secret.
`history_cmd`([search, limit, json_out])	Grep over `~/.claude/history.jsonl`.
`info_cmd`(session_id[, json_out])	Show full metadata + forensics for one session.
`kill_cmd`(session_id)	Kill the tmux session backing a live Claude Code session.
`list_cmd`([project, limit, include_forks, ...])	List Claude Code sessions across configured hosts, newest first.
`main`()	Entry point referenced by `pyproject.toml`'s `[project.scripts]`.
`mk_parser`()	The `xa` parser -- a plain `argparse.ArgumentParser`, built, not run.
`pick_cmd`([project, limit, host])	Interactive session picker — pick a row by number, then choose an action.
`resume_cmd`(session_id[, name, cwd, timeout, ...])	Resume a past session (`claude --resume`) in a new tmux pane.
`revive_cmd`([apply, include_held_elsewhere, ...])	Report — and optionally reconnect — panes whose Remote Control dropped.
`serve_cmd`([host, port, mount, username, ...])	Run the xa HTTP service (requires the `xa[service]` extra).
`spawn_cmd`(cwd[, name, timeout, ...])	Spawn a detached claude-in-tmux session and print its remote URL.
`sync_cmd`([host, force])	Refresh remote-host caches (SSH hosts; HTTP is always fresh).

xa.cli.archive_forensics_cmd(archive_id)[source]¶

Print rich forensics for an archived session as JSON.

Parameters:: archive_id (str) – Archive id from xa archive list.
Return type:: None

xa.cli.archive_list_cmd(limit=30, json_out=False)[source]¶

List archived sessions (created events, newest first).

Parameters:

limit (int) – Maximum rows (0 = unlimited).
json_out (bool) – One JSON object per line.

Return type:

None

xa.cli.archive_log_cmd(archive_id, tail_kb=64)[source]¶

Print the pane log for an archived session.

Parameters:

archive_id (str) – The archive id (first column of xa archive list).
tail_kb (int) – Only print the last N KB (0 = full log).

Return type:

None

xa.cli.gen_secret_cmd(length=32)[source]¶

Print a cryptographically strong random hex secret.

Useful for XA_PASSWORD, XA_CAPTCHA_KEY, bearer tokens. Output is to stdout with a trailing newline; pipe it into anything.

Parameters:: length (int) – Byte length of the secret (hex output is 2x this).
Return type:: None

xa.cli.history_cmd(search=None, limit=20, json_out=False)[source]¶

Grep over ~/.claude/history.jsonl.

Parameters:

search (Optional[str]) – Case-insensitive substring to filter on (display field).
limit (int) – Maximum rows to emit (0 = unlimited).
json_out (bool) – Emit one JSON object per line.

Return type:

None

xa.cli.info_cmd(session_id, json_out=False)[source]¶

Show full metadata + forensics for one session.

Parameters:

session_id (str) – Full UUID or unique prefix (e.g. first 8 chars).
json_out (bool) – Emit a single JSON object.

Return type:

None

xa.cli.kill_cmd(session_id)[source]¶

Kill the tmux session backing a live Claude Code session.

Parameters:: session_id (str) – Full UUID or unique prefix, or a tmux session name.
Return type:: None

xa.cli.list_cmd(project=None, limit=30, include_forks=True, no_live=False, state=None, host=None, json_out=False)[source]¶

List Claude Code sessions across configured hosts, newest first.

Parameters:

project (Optional[str]) – Substring match against session cwd (case-insensitive).
limit (int) – Maximum rows to show (0 = unlimited).
include_forks (bool) – Include sessions spawned with claude --resume.
no_live (bool) – Skip the tmux/ephemeral scan (archive-only view).
state (Optional[str]) – Restrict to ‘live’, ‘archived’, or ‘transcript_only’.
host (Optional[str]) – Restrict to a single configured host by name.
json_out (bool) – Emit one JSON object per line instead of a table.

Return type:

None

xa.cli.main()[source]¶

Entry point referenced by pyproject.toml’s [project.scripts].

Return type:: None

xa.cli.mk_parser()[source]¶

The xa parser – a plain argparse.ArgumentParser, built, not run.

Two calls rather than one cw.dispatch(...) because the archive group carries group_kwargs (its one-line help in the top-level listing), and a single mapping has nowhere to put those.

Return type:: ArgumentParser

xa.cli.pick_cmd(project=None, limit=30, host=None)[source]¶

Interactive session picker — pick a row by number, then choose an action.

A pragmatic v1 picker without a TUI framework. Use xa list for scripting; use xa pick when a human is at the keyboard.

Return type:: None

xa.cli.resume_cmd(session_id, name=None, cwd=None, timeout=120.0, model=None, effort=None)[source]¶

Resume a past session (claude --resume) in a new tmux pane.

Parameters:

session_id (str) – Full UUID or unique prefix.
name (Optional[str]) – Session name — tmux session and claude display name (auto if omitted).
cwd (Optional[str]) – Override cwd (defaults to the original session’s cwd).
timeout (float) – Seconds to wait for the bridge URL.
model (Optional[str]) – Per-session claude --model (omitted → claude’s default).
effort (Optional[str]) – Per-session claude --effort (omitted → claude’s default).

Return type:

None

xa.cli.revive_cmd(apply=False, include_held_elsewhere=False, server_mode=False, min_interval=0.0, json_out=False)[source]¶

Report — and optionally reconnect — panes whose Remote Control dropped.

Prints one line per live claude pane with its verdict, so “nothing to do” is legible next to how much was looked at. Sends nothing without --apply.

Parameters:

apply (bool) – Actually send /remote-control. Off by default.
include_held_elsewhere (bool) – Also reconnect sessions taken over from another device. This steals them back — deliberate keystroke only.
server_mode (bool) – Also restart died claude remote-control servers.
min_interval (float) – Seconds before the same pane may be touched again (0 uses the default guard interval).
json_out (bool) – Emit JSON instead of the table.

Return type:

None

xa.cli.serve_cmd(host='127.0.0.1', port=8010, mount='', username=None, password=None, password_env=None, captcha=False, webui=True, default_folder=None, i_know_its_insecure=False)[source]¶

Run the xa HTTP service (requires the xa[service] extra).

Secure by default. Refuses to bind to a non-loopback interface without HTTP Basic credentials. Override this guardrail with --i-know-its-insecure only in locked-down deployments (e.g. behind an mTLS-terminating proxy).

Parameters:

host (str) – Bind host. 127.0.0.1 by default — only this machine.
port (int) – Bind port.
mount (str) – Optional mount prefix (e.g. /api/xa).
username (Optional[str]) – HTTP Basic username.
password (Optional[str]) – HTTP Basic password. Prefer --password-env.
password_env (Optional[str]) – Name of env var to read the password from (recommended).
captcha (bool) – Enable captcha-gated deletes. Strongly recommended for any non-loopback deployment.
webui (bool) – Serve the bundled web UI at the mount root (default on). Pass --no-webui to run API-only.
default_folder (Optional[str]) – Default working directory the webui prefills into the “new session” dialog and the folder chooser opens at. Falls back to $XA_DEFAULT_FOLDER or $HOME if unset.
i_know_its_insecure (bool) – Skip the public-bind-without-auth safety check.

Return type:

None

xa.cli.spawn_cmd(cwd, name=None, timeout=120.0, no_remote_control=False, model=None, effort=None)[source]¶

Spawn a detached claude-in-tmux session and print its remote URL.

Parameters:

cwd (str) – Working directory to start claude in.
name (Optional[str]) – Session name — tmux session and claude display name (auto if omitted).
timeout (float) – Seconds to wait for the bridge URL.
no_remote_control (bool) – Spawn without passing --remote-control.
model (Optional[str]) – Per-session claude --model (omitted → claude’s default).
effort (Optional[str]) – Per-session claude --effort (omitted → claude’s default).

Return type:

None

xa.cli.sync_cmd(host=None, force=False)[source]¶

Refresh remote-host caches (SSH hosts; HTTP is always fresh).

Parameters:

host (Optional[str]) – Only sync this one host (default: all configured).
force (bool) – Sync even if the cache isn’t stale yet.

Return type:

None