Skip to main content
terma setup is the only onboarding step. Run it once per developer. There is nothing to run per repository: your team’s collection policy decides which repositories are collected.

​
Usage

​
What it does

1

Signs you in

Your browser opens on Terma, you approve the CLI, and a single-use code is handed back to terma on 127.0.0.1 (PKCE). A sign-in that still works is reused. --no-browser prints the URL instead of opening it. On a machine with no browser, such as a CI runner or an ephemeral VM, setup signs in with a team server key in TERMA_API_KEY instead: see Set up a machine with no browser.
2

Records which coding agents you use

A checklist preselects the agents installed on your machine. Each choice covers an agent’s CLI and its desktop app, which share the agent’s user-level settings:Cursor, OpenCode, and Antigravity appear as Coming Soon and cannot be selected yet.
3

Chooses your team and fetches its policy

--team names the team. Without it, setup uses your organization’s only team, or shows a picker. Setup then fetches the team’s collection policy and shows what it collects.
4

Points your agents at the local relay

Your agents’ user-level telemetry is sent to a relay terma runs on 127.0.0.1, as a per-user background service. The relay forwards only sessions in repositories your team collects, with only the content the policy allows. Because Claude Desktop, Codex Desktop, and IDE extensions read the same user-level settings, they are covered too.
5

Writes the machine-wide hooks

Each agent’s machine-wide hooks record its sessions and the files it edits. Setup approves terma’s own Codex hooks for you. It does not change git’s configuration, and writes nothing into a repository’s working tree or committed files.
Setup ends with a summary:
Restart any coding agent that was already running. An open Claude Code or Codex session keeps the configuration it started with.

​
Run it again

Setup is safe to run again, and running it again is how you change anything: terma login is an alias for terma setup.

​
Which repositories are collected

Your team’s collection policy is set in Terma by an organization admin (Team settings → Data collection). It collects either every session on the machine, inside git or not, or only the repositories it lists. A listed repository is written host/owner/name, for example github.com/acme/api; a longer path matches a GitLab subgroup. A session is collected only inside a git working copy whose origin remote matches an entry, ignoring case. HTTPS, SSH, and git@host:path forms all match, with or without .git, and a linked worktree uses its main repository’s origin. A folder outside git, or a repository with no origin, is never collected by a list. An empty list collects nothing.
An SSH host alias such as git@github-work:acme/api does not match github.com/acme/api. Point origin at the real host and choose the key with core.sshCommand. terma doctor shows the origin terma sees.
Each session reports to the team of the developer who ran it, so two developers on different teams in one repository each report to their own.

​
Flags

Non-interactive setup

​
What gets stored

  • Your sign-in and team keys are kept in the system keychain, or in plain text under ~/.config/terma with --insecure-storage or when no keychain is usable. On a machine set up with a server key, the key is kept as the team’s key.
  • Your choices (organization, team, agents) are kept in ~/.config/terma.
  • What terma writes as it runs (the event queue, the relay, the hooks’ state) lives in ~/.local/state/terma.
  • Your agents’ user-level settings gain terma’s telemetry exporter and hooks. terma teardown restores them.

​
Next step

terma doctor

Check the whole chain end to end.