Run The Companion

The Dots companion is the machine-local process that watches your bound folders and tails the coding-agent conversation sources you consented to share. It pushes both streams to the deployed Dots API named by your stored credential. It is separate from dots local, which runs a Dots backend on the same machine.

The family has seven executable commands. login-item is a group that contains three of them, not an eighth verb. When you arm a watched local binding or consented coding-agent sync, the CLI starts or refreshes the companion and registers its current command to run when you sign in. The login-item commands let you inspect or change that registration directly.

Before You Start

Install the CLI and confirm that dots auth whoami resolves the expected identity. The supervised start refuses before spawning when there is no usable stored credential, and the companion is for a deployed API rather than the local-daemon posture. You can still use the status and stop commands when the companion is down or its credential needs attention, because those commands operate against its machine-local control plane.

Start The Companion

dots companion start

start launches the companion as a detached supervised process. If the companion is already running, the lifecycle reports that state instead of launching a duplicate. The spawned process runs the same installed CLI entry as dots companion run. After moving or reinstalling the CLI, run login-item enable directly or arm watched work again to replace a stale sign-in command.

Use start for ordinary background operation: the companion watches its assigned local sources in a detached process, so the terminal returns immediately.

Stop The Companion

dots companion stop

stop asks the companion to shut down through its loopback control plane. The supervisor has a bounded kill fallback when that control request cannot complete. Removing a login item does not stop an already running companion, so use stop when you want the current process to end.

Read Companion Status

dots companion status

status reports liveness, process id, control port, target API, home directory, and process identity when those values are available. It always exits successfully; the record carries whether the process is down, running, or not the expected companion. That makes the command suitable for an operator check without treating an intentionally stopped companion as a command failure.

Run In The Foreground

dots companion run

run hosts the companion in the foreground until you interrupt it with Ctrl-C. It is the same process body that supervised start spawns: it resolves the stored credential, serves the loopback control plane, watches local folders, and tails consented coding-agent conversations. Diagnostics go to standard error while standard output remains empty.

Use foreground mode when you want the process attached to the current terminal for direct observation.

Enable Sign-In Startup

dots companion login-item enable

login-item enable records the exact installed CLI command and invokes dots companion start at sign-in. The implementation uses a per-user Windows run-key value, a macOS LaunchAgent, or a Linux systemd user unit. Other platforms return a typed usage error.

Because the recorded entry contains the current executable and CLI paths, run enable again after moving or reinstalling Dots when you do not otherwise arm watched work. Ordinary dots companion start remains process-only; the watched-work hooks are what maintain sign-in startup automatically.

Disable Sign-In Startup

dots companion login-item disable

login-item disable removes the per-user registration. It is safe when no login item is present and does not affect a companion that is already running. Pair it with dots companion stop when you want both the current process and future automatic starts to end. Disabling is not permanent: arming a watched local binding or coding-agent sync later registers the current command again so that work remains watched after sign-in.

Read Sign-In Startup Status

dots companion login-item status

login-item status reports whether the registration is enabled and, when readable, the exact command it runs. Like companion process status, it always exits successfully; an absent or unreadable registration is reported as not enabled rather than as a failed query.

The process and login-item status commands answer different questions. Use dots companion status to learn what is running now, and use dots companion login-item status to learn what the operating system is configured to start at the next sign-in.

For the complete generated command inventory, see CLI Reference. For the consented transcript workflow the companion tails, see Import Your Coding-agent Conversations.