# The rendered --help of every htalk command and subcommand, as the executable prints it.

==> htalk --help
htalk: durable local messages with optional client notifications.

Usage: htalk [OPTIONS] <COMMAND>

Commands:
  catalog  Publish profiles and find known devices through pinned SSH, LAN, active Bluetooth PAN or Tailscale.
  mcp      Expose this peer's mailbox tools over MCP stdio.
  receive  Forward a remote watch stream to an existing Codex CLI session.
  peer     Discover, register, check and retire session addresses.
  migrate  Prepare this mailbox without another operation.
  send     Save a request and attempt one notification.
  reply    Save an answer to an exact request.
  wait     Wait for an answer to a saved request.
  show     Read a saved message and its correlated answer without acknowledging.
  ack      Record that you read an incoming message. A question stays open until answered.
  inbox    List incoming work that remains open.
  watch    Stream incoming message notices as JSON lines until interrupted.
  sent     List outgoing messages and recover their IDs.

Options:
      --version    show program's version number and exit
      --db <PATH>  Shared SQLite file. Default: HTALK_DB, then $XDG_DATA_HOME/harness-talk/mail.sqlite3, then ~/.local/share/harness-talk/mail.sqlite3. Only peer add creates a missing file.
      --as <NAME>  Your registered peer name; overrides HTALK_PEER. Without either, message commands use the peer registered for the Claude Code session running them, if recognized.
  -h, --help       Print help

Setup: use one shared database and register both participants.
  htalk peer discover
  htalk peer add --help

Exchange, using each session's own registered name:
  htalk --as alice send bob --message 'Please check this.' --wait 45
  htalk --as bob inbox
  htalk --as bob ack REQUEST_ID
  htalk --as bob reply REQUEST_ID --message 'Checked.'
  htalk --as alice wait REQUEST_ID
  htalk --as alice ack REPLY_ID
Read the body before ack. REQUEST_ID and REPLY_ID are message IDs from JSON,
not native session IDs. A reply has its own id and an in_reply_to request ID.

Put --db and --as before the command, or set HTALK_DB and HTALK_PEER.
Use htalk COMMAND --help, or htalk peer COMMAND --help, for examples.
Results are JSON; one that failed or is uncertain adds next_action and recovery.
Exit 0: completed, including send --wait that returned an answer. Exit 2:
invalid input, or an unconfirmed notification without an answer; the message
may be saved. Exit 130: interrupted; inspect recovery.

==> htalk catalog --help
Only explicitly published profiles are exported. Device discovery is unauthenticated; profile reads and mailbox calls require pinned SSH identity and a fixed endpoint. Never launches sessions or retries messages.

Usage: htalk catalog <COMMAND>

Commands:
  publish    Publish an existing peer; replace a profile binding explicitly with --profile-id.
  unpublish  Withdraw a published profile.
  export     Read only this endpoint's published profiles; no private session addresses.
  serve      Fixed SSH endpoint: accepts only the exact remote command catalog or mcp.
  advertise  Advertise this catalogue until stopped; no standalone daemon is installed.
  discover   Fetch profiles only from known, pinned devices through the selected channel.
  connect    Find this published profile and expose its checked MCP route on stdio.

Options:
  -h, --help
          Print help (see a summary with '-h')

==> htalk catalog publish --help
Publish an existing peer; replace a profile binding explicitly with --profile-id.

Usage: htalk catalog publish [OPTIONS] --config <CONFIG> --name <NAME> --role <ROLE> <PEER>

Arguments:
  <PEER>  Registered peer to publish.

Options:
      --config <CONFIG>     Private catalogue JSON; each endpoint fixes its own mailbox and sender.
      --name <NAME>         Profile display name.
      --role <ROLE>         What the profile is for.
      --device-name <NAME>  Device label, set by the first publication. [default: "htalk device"]
      --profile-id <UUID>   Replace this profile's binding.
      --ssh-port <PORT>     SSH port, set by the first publication. [default: 22]
  -h, --help                Print help

==> htalk catalog unpublish --help
Withdraw a published profile.

Usage: htalk catalog unpublish --config <CONFIG> <PROFILE_ID>

Arguments:
  <PROFILE_ID>  Profile UUID from publish or export.

Options:
      --config <CONFIG>  Private catalogue JSON; each endpoint fixes its own mailbox and sender.
  -h, --help             Print help

==> htalk catalog export --help
Read only this endpoint's published profiles; no private session addresses.

Usage: htalk catalog export --config <CONFIG>

Options:
      --config <CONFIG>  Private catalogue JSON; each endpoint fixes its own mailbox and sender.
  -h, --help             Print help

==> htalk catalog serve --help
Fixed SSH endpoint: accepts only the exact remote command catalog or mcp.

Usage: htalk catalog serve --config <CONFIG>

Options:
      --config <CONFIG>  Private catalogue JSON; each endpoint fixes its own mailbox and sender.
  -h, --help             Print help

==> htalk catalog advertise --help
Advertise this catalogue until stopped; no standalone daemon is installed.

Usage: htalk catalog advertise [OPTIONS] --config <CONFIG> --interface <INTERFACE>

Options:
      --config <CONFIG>        Private catalogue JSON; each endpoint fixes its own mailbox and sender.
      --interface <INTERFACE>  Advertise only on this local interface.
      --seconds <SECONDS>      Stop after this many seconds; 0 runs until stopped. [default: 0]
  -h, --help                   Print help

==> htalk catalog discover --help
Fetch profiles only from known, pinned devices through the selected channel.

Usage: htalk catalog discover [OPTIONS] --trust <TRUST>

Options:
      --trust <TRUST>            Private list of known device IDs, mailbox bindings and pinned SSH files.
      --interface <INTERFACE>    Inspect only this local interface.
      --via <VIA>                Choose one channel; never fails over a mailbox call. [default: lan] [possible values: lan, bluetooth, tailscale, ssh]
      --tailscale-binary <PATH>  Owned Tailscale 1.102.x executable, used only with --via tailscale. [default: /usr/bin/tailscale]
      --tailscale-socket <PATH>  Local Tailscale daemon socket, used only with --via tailscale. [default: /var/run/tailscale/tailscaled.sock]
      --seconds <SECONDS>        Seconds to look on lan or bluetooth, 1–30. [default: 5]
  -h, --help                     Print help

==> htalk catalog connect --help
Find this published profile and expose its checked MCP route on stdio.

Usage: htalk catalog connect [OPTIONS] --trust <TRUST> <PROFILE>

Arguments:
  <PROFILE>  Canonical UUID selects only that profile identity, with no name fallback. Other inputs match display names exactly. For UUID-shaped or duplicate names, use the profile's own UUID.

Options:
      --trust <TRUST>            Private list of known device IDs, mailbox bindings and pinned SSH files.
      --interface <INTERFACE>    Inspect only this local interface.
      --via <VIA>                Choose one channel; never fails over a mailbox call. [default: lan] [possible values: lan, bluetooth, tailscale, ssh]
      --tailscale-binary <PATH>  Owned Tailscale 1.102.x executable, used only with --via tailscale. [default: /usr/bin/tailscale]
      --tailscale-socket <PATH>  Local Tailscale daemon socket, used only with --via tailscale. [default: /var/run/tailscale/tailscaled.sock]
      --seconds <SECONDS>        Seconds to look on lan or bluetooth, 1–30. [default: 5]
  -h, --help                     Print help

==> htalk mcp --help
Run a local MCP stdio server with a fixed database and peer, or keep a client connection alive while connecting to a remote mailbox separately for each tool call. Local mode requires --as or HTALK_PEER. Remote mode uses --connect -- COMMAND ARGS; that owner-configured command must reach a fixed htalk MCP endpoint. Calls are never automatically retried. This server does not wake an idle agent.

Usage: htalk mcp [OPTIONS] [-- <CONNECTOR>...]

Arguments:
  [CONNECTOR]...
          Owner-configured executable and arguments; executed directly, without a shell.

Options:
      --connect
          Connect to a fixed remote htalk MCP endpoint per call. Put its command after --; do not pass local --db or --as.

      --catalog <CATALOG>
          Expose the fixed published catalogue binding in the MCP handshake; local mode only.

      --expect-catalog <CATALOG>
          Private expected catalogue binding; reject a changed endpoint before every tool call.

  -h, --help
          Print help (see a summary with '-h')

==> htalk receive --help
Keep one existing Codex CLI session informed by a fixed remote htalk watch command. The receiver reconnects read-only watches and durably records each native queue receipt. Uncertain submissions stop for inspection. It does not launch a worker, acknowledge mail, or prove task completion. Use that session's remote htalk MCP tool for mailbox access.

Usage: htalk receive [OPTIONS] --peer <PEER> --session <SESSION> --workspace <WORKSPACE> --state <STATE> -- <CONNECTOR>...
       htalk receive <COMMAND>

Commands:
  status  Inspect saved receipts and the local Codex target without waking it.
  rebind  Bind stopped receiver state to a replacement socket hosting the same session.

Arguments:
  <CONNECTOR>...
          Fixed watch executable and arguments, after --; no shell.

Options:
      --peer <PEER>
          Mailbox peer the remote watch runs as.

      --session <SESSION>
          Existing Codex session UUID to notify.

      --workspace <WORKSPACE>
          That session's workspace path.

      --state <STATE>
          Private receiver directory. Keep it across reconnects and restarts.

      --mcp-command <PATH>
          Absolute executable for the same fixed MCP mailbox. Recheck each message before waking; no arguments or shell. Keep this binding across restarts.

      --codex-socket <PATH>
          Explicit local Codex app-server Unix socket hosting this session. Use its existing native adapter instead of codex queue; never fall back to another server.

  -h, --help
          Print help (see a summary with '-h')

==> htalk receive status --help
Inspect saved receipts and the local Codex target without waking it.

Usage: htalk receive status --state <STATE>

Options:
      --state <STATE>  The receiver's --state directory.
  -h, --help           Print help

==> htalk receive rebind --help
After explicitly resuming the same Codex session at the saved socket path, verify its UUID and workspace and accept the replacement listener. Preserves receipts; refuses active receivers and unresolved submissions. Does not resume, queue, or resend work.

Usage: htalk receive rebind --state <STATE>

Options:
      --state <STATE>
          The receiver's --state directory.

  -h, --help
          Print help (see a summary with '-h')

==> htalk peer --help
Discover sessions and manage registered addresses. These commands do not message peers.

Usage: htalk peer <COMMAND>

Commands:
  add       Register an immutable native or pull peer.
  list      List registered peer addresses.
  discover  Find native session addresses.
  check     Check a registered session's identity without messaging.
  retire    Refuse new requests to or from a peer that is no longer used.
  restore   Allow new requests to or from a retired peer again.

Options:
  -h, --help
          Print help (see a summary with '-h')

Start with htalk peer discover, then htalk peer add --help.
After registering: htalk peer check NAME
When a session is no longer used: htalk peer retire NAME
Use the same --db PATH before peer for both sessions.

==> htalk peer add --help
Save a peer name and native session address, or select --delivery pull for inbox polling without an address. Existing names cannot be reassigned. Does not notify or launch a client.

Usage: htalk peer add [OPTIONS] --harness <HARNESS> <NAME>

Arguments:
  <NAME>
          Local name: 1–64 lowercase letters, digits, _ or -; start with a letter or digit.

Options:
      --harness <HARNESS>
          Harness label. Native: codex, claude or opencode. Pull: any lowercase peer-style ID.

      --delivery <DELIVERY>
          Native client notification, or inbox polling without a native session.

          [default: native]
          [possible values: native, pull]

      --session <SESSION>
          Exact ID from discovery: Codex/Claude UUID or OpenCode ses... ID.

      --workspace <WORKSPACE>
          Session workspace path; must match after resolving paths.

      --socket <SOCKET>
          Codex only: explicit standalone app-server Unix socket. Omit to use native codex queue.

      --url <URL>
          OpenCode only: loopback server URL (default: http://127.0.0.1:4096).

  -h, --help
          Print help (see a summary with '-h')

Examples, with the exact session ID and workspace from discovery:
  htalk peer add alice --harness codex --session SESSION_UUID --workspace /project
  htalk peer add bob --harness claude --session SESSION_UUID --workspace /project
  htalk peer add muse --harness opencode --session ses_ID --workspace /project --url http://127.0.0.1:4096
  htalk peer add helper --harness generic --delivery pull

Register both peers in the same database. Then run htalk peer check NAME.

==> htalk peer list --help
Read registered peer names and their immutable session addresses. Retired peers are hidden unless --all is given.

Usage: htalk peer list [OPTIONS]

Options:
      --all
          Include retired peers; their retired_at is set.

  -h, --help
          Print help (see a summary with '-h')

Example: htalk --db /shared/mail.sqlite3 peer list
These are saved addresses; use peer check NAME to inspect a recipient now.
retired_hidden counts the retired peers left out.

==> htalk peer discover --help
Find native session addresses without registering or messaging them. Source statuses describe discovery coverage; an empty result does not prove that no client is running.

Usage: htalk peer discover [OPTIONS]

Options:
      --harness <HARNESS>
          Inspect only this client (default: all three).

          [possible values: codex, claude, opencode]

      --workspace <WORKSPACE>
          Only return sessions matching this resolved workspace path.

      --codex-socket <PATH>
          Inspect this running app-server socket; repeat for several servers.

      --opencode-url <URL>
          Inspect this local OpenCode server; repeat for several servers.

  -h, --help
          Print help (see a summary with '-h')

Examples:
  htalk peer discover --harness claude --workspace /project
  htalk peer discover --harness opencode --opencode-url http://127.0.0.1:4096
Use sessions[].session_id and workspace with peer add; inspect sources for gaps.

==> htalk peer check --help
Verify available identity evidence for a registered peer. Run in the scope that will send; unavailable evidence does not prove that the client is offline.

Usage: htalk peer check <NAME>

Arguments:
  <NAME>
          Registered peer name.

Options:
  -h, --help
          Print help (see a summary with '-h')

Example: htalk peer check bob
Run this before send. A successful check does not prove message receipt.

==> htalk peer retire --help
Mark a registered peer retired. New requests to or from it are refused, and notices to it are skipped. Replies to saved requests, inbox, show, wait and ack keep working. The name and session stay bound.

Usage: htalk peer retire <NAME>

Arguments:
  <NAME>
          Registered peer name.

Options:
  -h, --help
          Print help (see a summary with '-h')

Example: htalk peer retire bob
peer list then hides bob; peer list --all shows its retired_at. Repeating keeps
the first time.

==> htalk peer restore --help
Clear a peer's retirement. Notices skipped while it was retired are not sent. Repeating is safe.

Usage: htalk peer restore <NAME>

Arguments:
  <NAME>
          Registered peer name.

Options:
  -h, --help
          Print help (see a summary with '-h')

Example: htalk peer restore bob

==> htalk migrate --help
Ordinary mailbox commands automatically back up and upgrade schema 1/2 on first use. This optional command runs the same preparation on the database selected by --db, HTALK_DB or the default location. Verified backups are kept in PATH.backups. Older binaries reject schema 3. A failed migration rolls back; no automatic downgrade or backup restoration is performed.

Usage: htalk migrate

Options:
  -h, --help
          Print help (see a summary with '-h')

==> htalk send --help
Save a request before attempting one notification. After uncertain delivery, recover with show, wait or sent; do not send it again under a new ID.

Usage: htalk send [OPTIONS] <--message <MESSAGE>|--message-file <PATH>> <RECIPIENT>

Arguments:
  <RECIPIENT>
          Registered recipient peer name.

Options:
      --id <ID>
          Caller-generated UUID, saved before sending. An identical retry returns the saved request without another notification.

      --message <MESSAGE>
          Nonblank message body, at most 32,000 UTF-8 bytes.

      --message-file <PATH>
          Read the same message body from a local text file.

      --no-notify
          Save for inbox polling without notifying the client.

      --wait <SECONDS>
          Wait 0–45 seconds for an answer. An answer recorded by this wait before the final notification check skips that notice. It does not resend.

          [default: 0]

  -h, --help
          Print help (see a summary with '-h')

Example, after both peers are registered:
  htalk --as alice send bob --message 'Please check this.' --wait 45
Save id as REQUEST_ID. If reply is present, read reply.body and ack reply.id.
Otherwise continue with htalk --as alice wait REQUEST_ID.

==> htalk reply --help
Answer the exact incoming request. An identical retry returns the saved answer without another notification.

Usage: htalk reply [OPTIONS] <--message <MESSAGE>|--message-file <PATH>> <REQUEST_ID>

Arguments:
  <REQUEST_ID>
          Incoming request UUID from inbox or show.

Options:
      --message <MESSAGE>
          Nonblank message body, at most 32,000 UTF-8 bytes.

      --message-file <PATH>
          Read the same message body from a local text file.

      --no-notify
          Save for inbox polling without notifying the client.

  -h, --help
          Print help (see a summary with '-h')

Example: htalk --as bob reply REQUEST_ID --message 'Checked.'
The saved answer has its own id; the original sender acknowledges that answer.

==> htalk wait --help
Poll a saved outgoing request for its answer. Record the answer before returning it; a notification that sees this record at its final check is skipped. An already accepted notice may still arrive. Safe to resume after timeout or interruption; does not resend or acknowledge.

Usage: htalk wait [OPTIONS] <REQUEST_ID>

Arguments:
  <REQUEST_ID>
          Outgoing request UUID from send, sent or show.

Options:
      --seconds <SECONDS>
          Wait 0–45 seconds; 0 checks once.

          [default: 45]

  -h, --help
          Print help (see a summary with '-h')

Example: htalk --as alice wait REQUEST_ID --seconds 45
On timeout, use this same request ID again. If reply is present, read
reply.body, then run htalk --as alice ack REPLY_ID using reply.id.

==> htalk show --help
Read a saved message and its correlated answer without acknowledging.

Usage: htalk show <MESSAGE_ID>

Arguments:
  <MESSAGE_ID>  Message UUID from inbox, sent or another command's result.

Options:
  -h, --help  Print help

Example: htalk --as alice show MESSAGE_ID
Only the sender or recipient can show a message. ack_at is its read mark;
reply is the correlated answer, with its own id and ack_at.

==> htalk ack --help
Record that you read an incoming message. A question stays open until answered.

Usage: htalk ack <MESSAGE_ID>

Arguments:
  <MESSAGE_ID>  Message UUID from inbox, sent or another command's result.

Options:
  -h, --help  Print help

Example: htalk --as alice ack REPLY_ID
For an answer returned by wait, use reply.id, not the outgoing request's id.
Repeated ack is safe. Read notification_cleanup separately: ack may succeed
while cleanup fails. Use recovery.retry_notification_cleanup when returned.
Claude/OpenCode do not support withdrawing an already queued notice.

==> htalk inbox --help
Read incoming unanswered questions and unacknowledged answers, oldest first. Reading changes no acknowledgments.

Usage: htalk inbox [OPTIONS]

Options:
      --limit <N>
          Return at most N messages, 1–500.

          [default: 20]

      --after-seq <SEQ>
          Continue with messages newer than this seq; next_page supplies it.

  -h, --help
          Print help (see a summary with '-h')

Example: htalk --as bob inbox
Read messages[].body, then ack that message's id. Reply to a question
using the same id; acknowledging alone leaves the question open.
When omitted is above 0, run next_page for newer messages.

==> htalk watch --help
Emit ready, then a message event for each open inbox item. Polls locally without model calls. Reading changes no acknowledgments or delivery receipts.

Usage: htalk watch

Options:
  -h, --help
          Print help (see a summary with '-h')

Example: htalk --as bob watch
Use for a harness extension that queues notices into its current session.
Each event contains an id and notification text, not the peer's message body.
Open messages appear once per watcher; restarting replays unfinished work.
Always show the current message before acting. Run one receiver per peer.

==> htalk sent --help
Recover outgoing IDs after interruption, including messages with uncertain notifications, newest first. Does not resend.

Usage: htalk sent [OPTIONS]

Options:
      --limit <N>
          Return at most N messages, 1–500.

          [default: 20]

      --before-seq <SEQ>
          Continue with messages older than this seq; next_page supplies it.

      --bodies
          Return full message and answer texts.

  -h, --help
          Print help (see a summary with '-h')

Example: htalk --as alice sent
Use a saved request's id with show or wait. Inspect reply for its answer.
Texts are summarized as body_bytes and body_preview, the first nonblank line
up to 120 characters; show or --bodies returns them in full.
When omitted is above 0, run next_page for older messages.
A saved message with an uncertain notification must not be resent.
