Command-line reference

The exact trails setup, collection, service, backup, and configuration commands.

The one-command installer is the supported path for normal setup and updates. These commands are available in the installed standalone binary for inspection, recovery, and development.

Setup

trails setup hub [--name NAME] [--tailscale] [--service svc:NAME]
trails setup join URL [--name NAME]

setup hub always configures the current Mac as both canonical hub and collector. It installs server, collector, and backup services and performs the initial collection.

With no network flag, setup returns http://127.0.0.1:7412/. --tailscale additionally configures Tailscale Serve and returns the hub machine’s private MagicDNS HTTPS URL. --service svc:NAME implies Tailscale and advertises a pre-defined named Service.

setup join verifies an existing hub URL, configures this Mac as a spoke collector, performs its initial collection, and installs its collector service. --tailscale and --service are not valid for join mode.

Collect

trails collect --once [--server URL] [--device-id ID] [--device-name NAME] [--state PATH]

Runs one collection pass and exits. Without overrides it reads the installed collector configuration. The hub uses the same command to collect its own sessions.

Serve

trails serve [--db PATH] [--port PORT] [--api-only] [--static-dir PATH]

Starts the canonical HTTP service. Installed hubs use port 7412 and always bind to 127.0.0.1. Optional Tailscale Serve exposure proxies that loopback service; trails does not listen on the LAN.

Configure a collector

trails configure collector --server URL [--name NAME] [--reset-device-id]

Collector configuration sets the canonical hub endpoint and local display name. --reset-device-id intentionally creates a new collector identity on the next run.

Choose a summary harness

Run these commands only on the hub:

trails summaries status
trails summaries use [auto|omp|claude|codex|opencode|pi]
trails summaries off

trails summaries status lists installed harnesses and the effective selection. auto resolves Oh My Pi, Claude Code, Codex, OpenCode, then Pi. An explicit selection must be installed before Trails accepts it.

The harness owns provider/model selection and authentication. Trails invokes it non-interactively but never reads or writes its configuration or credential files.

Back up

trails backup --output PATH [--db PATH]
trails backup --output-dir DIR [--retain 14] [--db PATH]

Creates a consistent SQLite backup. Directory mode also prunes committed backups beyond the retention count.

Install launchd services

trails install server [--dry-run] [--tailscale] [--service svc:NAME]
trails install collector [--dry-run]

Writes and loads the launchd jobs used by the current configuration. --dry-run prints the planned files and commands without changing launchd.

--tailscale and --service are server-installation flags. They are rejected for collector installation. Ordinary setup should use trails setup hub or trails setup join rather than these lower-level commands.

Version and help

trails version
trails help