CLI reference

The relayfile CLI is the primary interface for humans and CI to work with Relayfile workspaces. It wraps the HTTP API and the mount sync engine into one tool: minimal flags, sensible defaults, composable with pipes (--json everywhere), and no implicit destructive actions (deletes require --yes).

Authentication

The CLI resolves a token in priority order, first match wins:

1. --token flag (one-off override)
2. RELAYFILE_TOKEN env var (CI/CD)
3. the canonical relay cloud session (cloud-hosted interactive use)
4. ~/.relayfile/credentials.json (self-hosted / API-key compatibility)

For the cloud-hosted path, login is owned by the agent-relay CLI: agent-relay login, then agent-relay workspace switch <name>, then any relayfile command. For self-hosted servers, use the API-key path:

relayfile login --api-key --server https://file.agentrelay.com

If no token is found, the CLI prints: Error: not authenticated. Run 'agent-relay login' for Cloud or set RELAYFILE_TOKEN.

relayfile setup

The low-friction Cloud setup path for humans and agent-guided onboarding. It ensures you're logged in, creates or joins a Cloud workspace, requests a hosted connect session for the chosen provider, waits until it reports ready, and starts the mount loop.

relayfile setup --provider notion --workspace my-project --local-dir ./relayfile-mount

Re-running with the same workspace name reuses the workspace, refreshes the session, and only opens a new connect flow when the provider isn't already connected. See Relayfile Cloud.

relayfile login

Authenticate through the canonical relay session, or the self-hosted API-key path.

relayfile login [--no-open]
relayfile login --api-key --server https://file.agentrelay.com

The default path delegates to agent-relay login. --api-key keeps the self-hosted compatibility path and writes ~/.relayfile/credentials.json with 0600 permissions.

relayfile seed

Bulk-upload a local directory into a workspace, respecting .gitignore.

relayfile seed my-workspace ./src

It walks the directory and posts batches to the bulk write endpoint, printing progress.

relayfile tree

List a remote workspace path without mounting.

relayfile tree my-workspace / --depth 2

Prints a compact human-readable tree by default; --json is for scripts. relayfile read <workspace> <path> (alias relayfile cat) reads a single file the same way.

relayfile listen

Stream the workspace event feed, optionally running a command per event.

relayfile listen \
  --path "/linear/issues/by-state/triage/**" \
  --event file.created \
  --run "claude --print 'Triage this: {{path}}'"

--run substitutes five placeholders into the command:

Events carry eventId, type, path, revision, provider, origin, correlationId, and — for small files — the content inlined. See Events and webhooks.

To keep a subscriber running across reboots, relayfile supervisor install accepts every listen flag and embeds them verbatim into a launchd (macOS) or systemd (Linux) unit that restarts on failure:

relayfile supervisor install \
  --path "/linear/issues/by-state/triage/**" --event file.created \
  --run "claude --print 'New triage issue at {{path}}. Assign it.'"
relayfile supervisor status

relayfile mount

Mount a workspace to a local directory, syncing changes in real time. This replaces the standalone daemon for end users.

relayfile mount my-workspace ./local-mirror

In poll mode the daemon maintains a synced mirror accelerated by a WebSocket invalidation channel. fuse mode is gated by build tags and unavailable in the OSS build (the CLI exits cleanly with a clear message rather than falling back silently). Stop a background mount with relayfile stop and tail its log with relayfile logs.

The relayfile-mount daemon

cmd/relayfile-mount is the minimal single-purpose daemon, kept for backwards compatibility and deployments that want it directly. It's configured by flags or environment variables:

RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
  --base-url http://localhost:9090 \
  --workspace ws_demo \
  --local-dir ./relayfile-mount \
  --remote-path /github \
  --fuse-content-ttl 10s

See Run locally for the daemon in context and Local development for the no-Docker loop.

Other commands

Global flags