The tempa CLI

tempa (client/, published as @devleaps/tempa) runs on the developer's laptop. It connects the device to a control plane, keeps the profile in sync and answers the harness's hooks.

Commands

A device login is scoped down: it never reads or changes the tenant's secrets, settings or domains, grants roles or invites people, or exports the tenant, whatever your roles. Do those in Tempa in your browser. Every command above keeps working with it (auth.md).

Which control plane

The first of these wins:

1. The MDM-managed file: /Library/Application Support/Tempa/config.json (macOS) or /etc/tempa/config.json (Linux), {"endpoint": "https://..."}. A --endpoint flag that disagrees is ignored with a warning.
2. tempa login --endpoint URL. A successful login with a flag saves it to ~/.tempa/config.json when there is no login for the current default endpoint yet, or with --default; otherwise the login is added next to the others and the default stays (Several endpoints).
3. ~/.tempa/config.json {"endpoint": "https://..."}.
4. https://tempa.devleaps.nl.

This is the default endpoint: every repo uses it unless it was pinned to another with tempa sync --endpoint. Plain http:// is accepted only for localhost and 127.0.0.1, for local development.

Files

File modes (TEMPA-225). When the CLI rewrites a file it keeps that file's mode: a ~/.claude/settings.json, ~/.gemini/settings.json or ~/.codex/config.toml you made 0600 (because it holds keys) stays 0600, and so does settings.json.tempa-backup. A file the CLI creates is 0600, except files in a repo (rendered assets, settings.local.json, .git/info/exclude) and lock-down packs, which get 0644 masked by your umask. Files with their own mode (the Codex hook script, 0755) get exactly that.

Sync and the profile cache

tempa sync [--repo PATH] resolves the repo of PATH (default: the current directory), fetches GET /v1/profile?harness=claude-code&repo=<raw remote>, verifies the Ed25519 signature against the discovery document's signing_keys and caches it. It exits 1 when it had to fall back to the cache.

• Repo: the URL of origin, else of the first remote, sent as is; the server and the CLI normalise it the same way (git@github.com:Org/Repo.git → github.com/org/repo; client/src/repo.ts is a port of api/tempa_api/profile/repo.py, keep them in step). Outside git, or in a repo without remotes, no repo is sent and the server answers with the default team profile.
• Signature: a profile that does not verify is refused and not cached. A key id the CLI does not know makes it fetch the discovery document once more (key rotation) before refusing.
• Cache: ~/.tempa/cache/<sha256(repo key)>/profile.json and meta.json (endpoint, fetched_at, node, matched by, etag). The repo key is the normalised remote, or @default. The discovery document is cached in ~/.tempa/cache/discovery.json (refetched after 24 hours) so cached profiles can be verified offline. A cached profile is used only while it is not past expires_at, comes from the current endpoint and still verifies, so editing it on disk makes it unusable. tempa logout clears the cache.
• Offline: when the control plane cannot be reached, the cached profile is used until it expires.
• Speed: the SessionStart hook uses the cache without a request while it is younger than the profile's sync_interval (default 15 minutes). A warm sync is one git call plus reading and verifying two files.

Rendering into Claude Code

After a sync inside a git working tree, tempa sync (and the SessionStart hook) writes the profile into the repo without anything reaching its history. This is the Claude Code renderer; how renderers and the shared apply step work for every harness is in harnesses.md.

• Every Markdown file carries `. Where the asset has YAML frontmatter, the frontmatter stays first and the header follows it. Skills and agents getname: tempa-<name>` so Claude Code's name matches the folder or file (frontmatter is created when the asset has none).
• Every rendered path is listed in .git/info/exclude between # >>> tempa and # <<< tempa. Tempa never edits .gitignore, and never writes a path git tracks (it reports it and skips it). A file at a Tempa path that Tempa did not write is not overwritten either.
• settings.local.json: the developer's own entries and other keys stay as they are. Tempa only adds the profile's rules that are missing, and later removes only the rules it added.
• The manifest .git/tempa-manifest.json (per worktree: git rev-parse --git-path tempa-manifest.json) records each rendered file with the sha256 of what was written, the permission rules Tempa owns, the excluded paths and the profile version (manifest version 2; a version 1 manifest from an older CLI is migrated on the next sync). A sync removes files from an older profile; one the developer edited since is left in place (and stays excluded). tempa doctor compares the files with the manifest to report drift, and the next sync restores edited files.
• Outside a git repo nothing is written into the directory.

Rendering into GitHub Copilot

tempa sync --harness copilot (and the Copilot plugin's sessionStart hook) renders the same profile where GitHub Copilot reads it (TEMPA-162, client/src/render/copilot.ts). Everything above holds the same way, with Copilot's own manifest (tempa-manifest-copilot.json next to Claude Code's) and its own block in .git/info/exclude (# >>> tempa:copilot), so the two renders never remove each other's files.

• applyTo: a standard's own applyTo stays; otherwise Claude Code's paths (a string, an inline list or a block list) become a comma-separated applyTo, and a standard without either applies to every file (applyTo: "**"). paths is dropped. The asset's description is added when the frontmatter has none.
• Commands: the Copilot CLI has no command files, and it invokes a skill as /<name>, so a command becomes the skill tempa-<name>, whose description says to use it when the developer asks for the command. A skill with the same name wins; Claude Code-only keys (allowed-tools, model, ...) are dropped.
• Agents: Claude Code's model and color are dropped (Copilot does not know Claude Code's model aliases); tools stays, since Copilot maps Claude Code's tool names by alias (Read, Grep, Bash, ...).
• A team's own committed .github/... file is never overwritten; only tempa-* paths are Tempa's.
• tempa doctor checks Copilot's render as well (Rendered files (GitHub Copilot), Git exclude (GitHub Copilot)) once a repo has one.

Rendering into Codex

tempa sync --harness codex (and the Codex plugin's SessionStart hook) renders the profile where OpenAI Codex reads it (TEMPA-144, client/src/render/codex.ts), with its own manifest (tempa-manifest-codex.json) and its own block in .git/info/exclude (# >>> tempa:codex).

• The size cap. Codex reads one instructions file per directory, from the project root down to the working directory, and stops adding files once they reach 32 KiB together (project_doc_max_bytes). Tempa keeps the root file within 24 KiB, which leaves room for the repo's own AGENTS.md files in subdirectories. Locked standards come first; standards go in full until one no longer fits, and from there each is one line with a pointer to its full text. A file over the budget is reported, never cut.
• A committed AGENTS.md. Tempa never overwrites it, and Codex reads only one file per directory, preferring AGENTS.override.md. So Tempa writes AGENTS.override.md (git-excluded) with the repo's own text first and Tempa's standards after it, counted together against the budget. It follows the committed file at every sync; between syncs an edit to AGENTS.md only reaches Codex after the next one. An AGENTS.md the developer wrote but did not commit (no Tempa marker) is left alone and reported.
• Agents: developer_instructions is the agent's body; its description comes from the frontmatter or the asset. Claude Code's frontmatter (tools, model, color, ...) is dropped and reported: Codex's agent files take Codex models and no tool list.
• Permission rules (rules): Codex reads prefix_rule(pattern = [...], decision = ...) from .codex/rules/*.rules once the project is trusted, and the most restrictive matching rule wins. Bash(<prefix>:*) and Bash(<prefix> *) are prefixes. A plain Bash(<command>) ask becomes a prefix rule on its words, which asks a little more often, never less; as a deny it is left out, so Codex never forbids more than Claude Code denies. Rules with wildcards elsewhere, quoting or other tools (Read(...)) are left out. Allow rules are not rendered: Codex's allow runs a command outside its sandbox. The hook uses the same rules (see hooks.md).
• Other harnesses reading these files. GitHub Copilot also reads AGENTS.md and .agents/skills, so on a machine with both, a Copilot session sees Tempa's standards and skills twice (as Codex's and as its own).
• tempa doctor checks Codex's render as well (Rendered files (Codex)) once a repo has one.

Rendering into Gemini CLI

tempa sync --harness gemini-cli (and the Gemini extension's SessionStart hook) renders the profile where the Gemini CLI reads it (TEMPA-154, client/src/render/gemini.ts), with its own manifest (tempa-manifest-gemini-cli.json) and its own block in .git/info/exclude (# >>> tempa:gemini-cli).

• Context files are read without ignore rules. Gemini finds its context files from the working directory up to the git root (memoryDiscovery.ts) and does not apply .gitignore or .git/info/exclude there, so the git-excluded file is read. It does load them only in a trusted folder.
• No size cap. Gemini documents none, so every standard is in full (Codex's 32 KiB cap does not apply).
• A committed GEMINI.md is never overwritten. Gemini reads every name in context.fileName in each directory, so Tempa writes TEMPA.md and adds it to the names in the project's .gemini/settings.json (keeping the names Gemini read before). When the repo commits .gemini/settings.json too, that edit is skipped and reported, and TEMPA.md is not read: name it in your own context.fileName.
• Next to Codex. Gemini also reads .agents/skills (and prefers it) and, through context.fileName, maybe AGENTS.md. A skill or the standards Codex's render already wrote there are not rendered again for Gemini, and reported (codexFiles from Codex's manifest).
• Commands: Gemini has {{args}} for the whole argument text and no positional arguments, so a body with $1, $2 keeps them as text after a note that says what they mean, and is reported. argument-hint becomes a line in the prompt; allowed-tools and model are dropped and reported.
• Agents: Read, Grep, Bash and the other Claude Code tools become read_file, grep_search, run_shell_command, ...; a tool without a Gemini name (an MCP tool) is left out and reported, and so are model and color.
• Permission rules at the user level. Gemini's workspace policies (.gemini/policies) are disabled in its source, so the rules go to the user's policies, which apply in every repo. The file holds the rules of the repo whose session (or tempa sync) rendered last, and its origin line says which profile that was. Gemini reads policies when it starts, so a change applies from the next session. The rules are a second line: they ask and deny even when a hook times out, and on a Gemini CLI that cannot ask from its hooks they are what asks (hooks.md). Bash(<prefix>:*) and Bash(<prefix> *) become commandPrefix; a plain Bash(<command>) ask becomes a prefix too (it asks a little more often), and as a deny it is left out.
• tempa doctor checks the render as well (Rendered files (Gemini CLI)) once a repo has one.

Rendering into Antigravity

tempa sync --harness antigravity (and the Antigravity plugin's SessionStart hook) renders the profile where Google Antigravity (the agy CLI, the App and the IDE) reads it (TEMPA-180, client/src/render/antigravity.ts), with its own manifest (tempa-manifest-antigravity.json) and its own block in .git/info/exclude (# >>> tempa:antigravity). Antigravity's customization docs were the source (read 2026-11-05); what only a real agy can confirm is in TEMPA-185.

• 24,000 bytes per rule. A standard whose rule would be larger is summarised in its rule with a pointer to its full text in .agents/tempa-standards/<name>.md (standards-within-size-cap), outside .agents/rules so it is not a rule itself; the sync reports it. Antigravity gives always-on rules 20,000 tokens together and turns the rest into pointers the agent reads on demand.
• Next to Codex. Codex renders the same .agents/skills/tempa-<name>/ and the repo-root AGENTS.md, and Antigravity reads both. A skill (or command) whose SKILL.md Codex's render holds is not rendered again; a copy Antigravity's render wrote before is handed over to Codex and left in place (handedOver in the plan), never deleted. When Codex's render wrote AGENTS.md, Antigravity reads the standards there and writes no rules. Codex's AGENTS.override.md is not one of the files Antigravity reads, so its rules are written then.
• Next to the Gemini CLI. Antigravity reads GEMINI.md too: when the Gemini CLI's render wrote it (or AGENTS.md), Antigravity writes no rules. With both Codex's AGENTS.md and Gemini's GEMINI.md, Antigravity sees the standards twice (both are always on and belong to their harness); the sync says so, and setting Gemini's context.fileName to AGENTS.md leaves one. TEMPA.md is not read by Antigravity. Gemini's .gemini/skills, .gemini/commands and .gemini/agents are not Antigravity folders.
• Only files of those renders that are still on disk count, so a deleted AGENTS.md brings Antigravity's rules back at the next sync.
• Agents: Read, Grep, Bash and the other Claude Code tools become view_file, grep_search, run_command, ...; a tool without an Antigravity name (an MCP tool, TodoWrite) is left out and reported, since an unknown tool name can hang the subagent. An agent left with no known tool gets tools: []. model (Claude's aliases are not Antigravity's inherit, flash, pro) and color are dropped and reported.
• Session start no longer carries the standards' text inside a git repo: the summary points at the rules. Outside git nothing is rendered, and the summary carries the standards as for the other harnesses.
• tempa doctor checks the render as well (Rendered files (Antigravity)) once a repo has one.

Antigravity permission rules

The profile's shell ask and deny rules also go into the Antigravity CLI's user settings (TEMPA-179, client/src/harness/antigravity-rules.ts), as a second line next to the hook's force_ask and deny (hooks.md): a deny there still holds when the hook fails open.

• A list merge Tempa owns. Tempa adds its entries to the lists and removes only those it added when the profile drops them; the developer's own entries, also one equal to Tempa's, and every other setting stay.
• User level, so the rules apply in every repo, and the file holds the rules of the repo whose session (or tempa sync) rendered last. That makes other repos stricter, never looser: allow rules are not rendered, since an allow there would skip Antigravity's own confirmation for every repo on the machine.
• What a prefix can say. Antigravity's command(...) matches a command word by word from its start. Bash(<prefix>:*) and Bash(<prefix> *) become command(<prefix>); a plain Bash(<command>) ask becomes a prefix too (it asks a little more often), and as a deny it is left out. Wildcards, quoting, shell operators and rules for other tools are left out and reported. Policies written in Rego cannot be rendered ahead of time; their asks follow the hook.
• The CLI only. The App and the IDE keep their permission rules somewhere the docs do not name, so they get only the hook's answers (TEMPA-185).
• Written by Antigravity's renderer (TEMPA-180) at session start and on tempa sync --harness antigravity; a settings file that is not valid JSON is left alone and reported.

Telemetry

Design and ingest rules: telemetry.md. What the CLI does:

• Claude Code's own telemetry. After every sync (tempa sync and SessionStart) Tempa writes its env block and otelHeadersHelper into ~/.claude/settings.json: CLAUDE_CODE_ENABLE_TELEMETRY=1, OTLP logs and metrics over http/protobuf to the discovery document's otel_endpoint, delta temporality and OTEL_RESOURCE_ATTRIBUTES=tempa.device=<device id>. OTEL_LOG_USER_PROMPTS and OTEL_LOG_TOOL_DETAILS are only set when the profile's telemetry.log_prompts / log_tool_details are on; with telemetry.enabled off the block is removed. Every other key in the file stays as it was. The file is copied once to settings.json.tempa-backup before Tempa first changes it, and ~/.tempa/claude-settings.json records which keys Tempa owns. tempa logout removes exactly those. Claude Code reads the block at start, so a change applies from the next session.
• Auth. otelHeadersHelper runs tempa otel-headers (with absolute node and CLI paths when known), which prints the headers of POST /v1/telemetry/token for the current repo, for example {"Authorization":"Bearer eyJ…"}. Tokens are cached in ~/.tempa/telemetry/<sha256(repo)>.json (0600) and renewed when less than 30 minutes are left; a still-valid cached token is used when the control plane is down.
• Tempa's own events are OTLP log records (service.name=tempa-cli, the event name as body and event.name, session.id when the event belongs to a session), spooled in ~/.tempa/spool/ and posted as OTLP/HTTP JSON to <otel_endpoint>/v1/logs with the repo's telemetry token:

  Event	Attributes	When
  profile.synced	profile_version, changed, duration_ms	a profile was fetched from the control plane
  policy.decision	decision, policy_ids (string array), bundle_version, tool_name, latency_ms	every PreToolUse that is not the read-only fast path; local MCP denials have policy id tempa/mcp-allowlist, offline decisions tempa/offline
  session.offline_cached	cache_age_seconds	first offline decision of a session with a cached profile
  session.offline_no_profile	none	first PreToolUse of a session without a profile
  render.drift	files, repo	a sync restored rendered files that had been edited

  Records that cannot be sent stay in the spool; records older than a week are dropped, and so is everything when the token says telemetry is off.

tempa setup

tempa setup (TEMPA-138) is the first command on a new machine, or after installing another harness. It only looks: a harness counts as found when its binary is on the PATH or its config folder exists. It never reads or changes the harness's files beyond checking whether Tempa's plugin is installed.

Per harness it prints whether it was found, what Tempa supports there (from the capability matrix: how many capabilities are native, which are degraded and by which rule, how its hooks fail; see harnesses.md) and, for a supported harness without the plugin, the exact commands. Without --yes nothing runs; with it, the commands run one by one (no shell), and the first failure stops that harness's install and makes the exit code 1. Where the harness has no command for a step (installing the Codex plugin), the report says what to do instead. --harness ID limits all of this to one harness.

For Antigravity it also lists the surfaces it found: the CLI (agy on the PATH), the App (/Applications or ~/Applications on macOS, %LOCALAPPDATA%\Programs\Antigravity on Windows, antigravity on the PATH on Linux; TEMPA_ANTIGRAVITY_APP names another place) and the IDE (its data folder, ~/.gemini/antigravity-ide). Where the App or the IDE is installed and the plugin is in place, --yes writes Tempa's tempa group into ~/.gemini/config/hooks.json (TEMPA-184, install.md): a JSON merge of that one key, written only when it differs from the installed plugin's hook lines. A file that is not a JSON object is left alone. tempa doctor reports the same (Antigravity surfaces, Antigravity user-level hooks, Antigravity hooks fired).

There is one login for all harnesses: credentials are stored per endpoint and tenant in ~/.tempa, and every plugin's hook runs the same tempa. tempa setup shows the login (without asking the control plane) and, when there is none, says to run tempa login once.

tempa doctor

Prints one line per check ([ ok ], [warn] or [FAIL]) and a Fix: line under anything that is not fine. It exits 1 when a check fails; warnings do not fail it. It first stores the node and tempa it runs with in ~/.tempa/node-path and ~/.tempa/cli-path for the plugin's launcher.

Cleaning up

tempa clean [--repo PATH] [--all] [--dry-run] (TEMPA-241) takes back what Tempa wrote, for every harness that rendered into the repo (Claude Code, Codex, Gemini CLI, Copilot, Antigravity): it renders an empty profile, which removes exactly the files Tempa wrote and nobody changed since and Tempa's own entries in settings files such as .claude/settings.local.json, then drops the harness's block from .git/info/exclude and its manifest. A file you changed after Tempa wrote it is kept and listed (it shows up in git status once the exclude block is gone). Running it again is harmless.

• Without flags: the repo of the current directory (--repo picks another).
• --all: every repo Tempa remembers rendering into (~/.tempa/rendered-repos.json, kept since TEMPA-241; a repo rendered by an older CLI is cleaned when you run tempa clean in it), plus Tempa's keys in ~/.claude/settings.json and the settings.json.tempa-backup it made. Use it before uninstalling.
• --dry-run: lists what it would remove and changes nothing.

User-level files of Codex, Gemini CLI and Antigravity (~/.codex/config.toml's Tempa block, Gemini's and Antigravity's user hooks and policies) are not taken back by tempa clean; tempa doctor names them, and their install guides say how to remove them. tempa logout is separate: it forgets the tokens and cached profiles.

Several tenants

A consultant can belong to several tenants, for example Devleaps and a client (TEMPA-066, auth.md). A device token is for exactly one tenant, so the laptop keeps one login per tenant:

tempa login                  # the tenant your sign-in belongs to: the default; lists your other tenants
tempa login --tenant acme    # a second login, for acme: the browser page names acme before you sign in
tempa status                 # every login
tempa logout --tenant acme   # forget only that one

tempa login --tenant asks for the tenant with the device code (TEMPA-113): the verification page says "Connecting <laptop> to Acme", and the server approves the device for acme only when you belong there (or hold an invite for a verified address, or may join through a verified domain). Not a member: the page says so and the CLI stops at once ("Login refused: You are not a member of tenant acme …"). The CLI also names the tenant when it collects the tokens, so a control plane from before TEMPA-113 still checks it there (auth.md).

Credentials file. ~/.tempa/credentials.json holds the default login at the top level, with the same fields a single login always had, and the logins for the other tenants under tenants, keyed by tenant id. CLI 0.1.x reads the default login from it unchanged; a file written by CLI 0.1.x (one login, no tenant) is read as the default login, its tenant taken from the access token's tid, and gets the new fields at the next write. If an older CLI rewrites the file (a refresh), it keeps the default login and drops the others: log in to them again. Logins of other control planes sit under endpoints (Several endpoints). Each login's tokens refresh on their own, under the same lock file.

Which tenant a repo uses. With one login there is nothing to decide. With several, tempa sync (and the SessionStart hook when its answer is older than a day) asks every logged-in tenant GET /v1/repos/resolve?remote=<git remote>, and caches the answer in ~/.tempa/repo-tenants.json:

An answer is cached only when every tenant answered; a tenant that cannot be reached never moves a repo. A control plane from before TEMPA-066 answers 404, which counts as not registered. tempa login forgets the resolved answers (the new login may change them), not the choices.

Everything for a repo uses its tenant's login: the profile (GET /v1/profile, cached with the tenant in meta.json; a cached profile of another tenant is not used), the hooks' /v1/decide and heartbeats (one per tenant device), telemetry tokens, and the MCP proxy's /v1/mcp/session. Hooks never ask the network which tenant a repo is in: they read the cached answer, else use the default tenant.

Several endpoints

A laptop can hold logins for more than one control plane (TEMPA-113): a client's dedicated installation next to the shared one, or dev next to prd. Each login belongs to one endpoint and one tenant there:

tempa login                                      # the default endpoint (see Which control plane)
tempa login --endpoint https://tempa.dev.example # a second endpoint, next to it; the default stays
tempa login --endpoint https://tempa.dev.example --tenant acme
tempa login --endpoint https://tempa.dev.example --default   # make it the default endpoint
tempa status                                     # every endpoint and its tenants
tempa sync --endpoint https://tempa.dev.example  # this repo uses that endpoint from now on
tempa logout --endpoint https://tempa.dev.example            # forget that endpoint's logins

Credentials file. Keyed by endpoint, then tenant, and readable by every older CLI:

{
  "endpoint": "https://tempa.devleaps.nl", "tenant": "devleaps", "access_token": "…", "…": "…",
  "tenants": { "acme": { "endpoint": "https://tempa.devleaps.nl", "tenant": "acme", "…": "…" } },
  "endpoints": {
    "https://tempa.dev.example": {
      "default": "devleaps",
      "tenants": { "devleaps": { "endpoint": "https://tempa.dev.example", "…": "…" } }
    }
  }
}

• the top level is the default endpoint's default login, the fields a single login always had: CLI 0.1.4 reads it unchanged;
• tenants are the default endpoint's other tenants, as TEMPA-066 wrote them;
• endpoints holds every other endpoint: its default tenant and its logins by tenant.

Every login names its own endpoint, so reading does not depend on where a login sits: an old single-login file and a TEMPA-066 file are read as they are and rewritten in this layout at the next write (migrate on read), and when the default endpoint changes (--default, ~/.tempa/config.json, the managed file) the next write moves that endpoint's default login to the top level. An older CLI that rewrites the file keeps the top level (and, from TEMPA-066 on, tenants); it may drop endpoints: log in to those again.

Which endpoint a repo uses. The default endpoint, and its tenant as in Several tenants, unless the repo was pinned with tempa sync --endpoint URL [--tenant ID] (kept in ~/.tempa/repo-tenants.json until you log out of that login; then it falls back to the default endpoint). Repo → tenant resolution stays per endpoint: only the default endpoint's tenants are asked. The profile, its cache (checked against that endpoint's discovery keys), /v1/decide, heartbeats, telemetry tokens and the MCP proxy all use the repo's login. The Claude Code env block in ~/.claude/settings.json is global and follows the default endpoint.

Discovery is cached per endpoint (~/.tempa/cache/discovery/<sha256(endpoint), 16 hex>.json), so every endpoint's profiles verify offline.

Tokens

The access token lives for an hour. Every request refreshes it when it has less than a minute left, and once more when the server answers 401 for another reason than a revocation. Refresh tokens rotate and a reused one logs the device out, so a lock file makes sure only one tempa process (hooks run in parallel) refreshes at a time; the others pick up the new tokens. A revoked device gets the server's own message, for example "This device was revoked on 2026-10-17. Run 'tempa login' to connect it again."

Config in CI (TEMPA-083)

A tenant whose config lives in a Git repository Tempa does not sync from (any host, any CI) checks it on every merge request and publishes it on merge with tempa config validate, diff and push.

Why through the API. The validator is tempa-api's (tempa_config, Python), and the CLI is Node. Rather than a second validator that drifts, validate and diff pack the folder as a tar.gz (.git left out) and send it to POST /v1/config/uploads/check, which validates it exactly as a publish would and compares it with the live version, without making a draft. So they need the network and a credential. Offline, from a checkout of this repo: cd api && uv run python -m tempa_config validate <dir>.

The credential: a config token. A platform owner makes one per pipeline, with their own device login:

tempa config token create --name gitlab-ci --days 90   # prints the token once: store it as the CI secret
tempa config token list
tempa config token revoke <id>

(or POST /v1/tenant/config-tokens {"name", "expires_in_days"}, GET /v1/tenant/config-tokens, POST /v1/tenant/config-tokens/{id}/revoke). A config token (tct_<tenant>.<secret>) works only in its tenant, may only validate, draft and publish the config (config.read, config.edit, config.publish: nothing else, not the MCP server), expires after at most a year and is refused at once when revoked. Tempa keeps only its SHA-256; making and revoking are audited (config_token.create, config_token.revoke), and what it does is audited as config-token:<name>. The CLI reads it from TEMPA_CONFIG_TOKEN (never a flag) and the control plane from --endpoint or TEMPA_ENDPOINT; without a config token it uses the device's login.

Exit codes

GitLab CI

# .gitlab-ci.yml (TEMPA_CONFIG_TOKEN and TEMPA_ENDPOINT as masked, protected CI/CD variables)
tempa-config:
  image: node:20
  before_script:
    - npm config set @devleaps:registry https://npm.pkg.github.com
    - npm install -g @devleaps/tempa
  script:
    - tempa config validate .
    - tempa config diff .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

tempa-config-push:
  image: node:20
  before_script:
    - npm config set @devleaps:registry https://npm.pkg.github.com
    - npm install -g @devleaps/tempa
  script:
    - tempa config push . --title "$CI_COMMIT_SHORT_SHA $CI_COMMIT_TITLE"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

GitHub Actions

# .github/workflows/tempa-config.yml (secrets TEMPA_CONFIG_TOKEN, variable TEMPA_ENDPOINT)
name: tempa-config
on:
  pull_request:
  push:
    branches: [main]
jobs:
  config:
    runs-on: ubuntu-latest
    env:
      TEMPA_CONFIG_TOKEN: ${{ secrets.TEMPA_CONFIG_TOKEN }}
      TEMPA_ENDPOINT: ${{ vars.TEMPA_ENDPOINT }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, registry-url: https://npm.pkg.github.com, scope: "@devleaps" }
      - run: npm install -g @devleaps/tempa
        env: { NODE_AUTH_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }
      - run: tempa config validate . && tempa config diff .
      - if: github.event_name == 'push'
        run: tempa config push . --title "${{ github.sha }}"

Use --draft to leave every push as a draft that a person publishes in tempa-web.

Overrides for tests and development

Releasing

Which versions stay supported, and how a version is deprecated, is in cli-versions.md. Bump version in client/package.json and in plugins/overlays/claude-code/.claude-plugin/plugin.json (the build refuses a mismatch), merge, then tag: git tag cli-v0.2.0 && git push origin cli-v0.2.0. .github/workflows/release-cli.yml tests, builds and publishes the package to GitHub Packages, builds every harness's plugin with the CLI inside (node client/build-plugins.mjs --cli client/dist/tempa.js), and commits each released plugin to its own branch (node client/build-plugins.mjs --released lists them): Claude Code's to plugin-release, which tempa@devleaps installs from, and GitHub Copilot's to plugin-release-copilot (Copilot's tempa@devleaps, since TEMPA-160). The other harnesses' plugins are built and checked on every pull request (the plugins CI job, artifact tempa-plugins) but not released until their epics ship. See harnesses.md.

The same tag also runs .github/workflows/build-binaries.yml. It builds the standalone binary for every platform, with Node inside, and keeps the binaries, their checksums and SBOMs as workflow artifacts only. It can also be run by hand (binaries.md).

To try a plugin change locally, from the repo root: node client/build-plugins.mjs (or pnpm --filter @devleaps/tempa build:plugins), then claude --plugin-dir dist/plugins/claude-code. Without a bundled CLI the launcher finds tempa through TEMPA_CLI or your PATH; add --cli client/dist/tempa.js after pnpm --filter @devleaps/tempa build to bundle it as the release does.