---
title: "Command-line reference"
description: "The exact trails setup, collection, service, backup, and configuration commands."
---

> Documentation Index
> Fetch the complete documentation index at: https://trails.manzanita.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line reference

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

```text
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

```text
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

```text
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

```text
trails configure collector --server URL [--name NAME] [--reset-device-id]
trails configure server --ai-url URL --ai-token-stdin
```

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

Server configuration enables the optional authenticated inference relay. The token is read from standard input so it does not appear in shell history or process arguments.

## Back up

```text
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

```text
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

```text
trails version
trails help
```

Source: https://trails.manzanita.dev/reference/cli/index.mdx