Installation

The Pulse CLI connects local development to Pulse. It authenticates your machine, initializes and links projects, records the events only you can author, publishes deployment metadata, and synchronizes execution that happened while you were offline.

The CLI is a single binary distributed on npm. It holds no state beyond a credential in your home directory and a pulse.json in each project. It is designed to be run by a person at a terminal and by a machine in a pipeline, with no difference in behavior between the two beyond how it is authenticated.

Most of what Pulse records happens where the browser cannot see it: on your machine and in your pipeline. The CLI is how that execution reaches the record without anyone stopping to type it into a form.

We could have built the whole product around webhooks and a web UI, and for a while we tried. It fails in two places. Deployments know things only the deploying machine knows — the version, the environment, the commit that was actually shipped rather than the one that was merged — and a webhook does not carry them. And engineers do not stop mid-incident to open a browser tab; if recording a BLOCK costs a context switch, it does not happen, and an unrecorded incident is an incident that never entered the record.

So the CLI exists to make capture cost nothing. It runs where the work is, it is scriptable, and it is safe to put in a pipeline. That is also why it is deliberately small: it does not lint, build, deploy, or manage your infrastructure. It records.

• Credential — a machine token written to ~/.pulse/credentials.json by pulse login. It authenticates the machine, not a session, and it does not expire on you mid-incident.
• pulse.json — per-project configuration, committed to the repository. It contains no secrets.
• PULSE_TOKEN — the environment variable used to authenticate in CI, where an interactive browser login is impossible.
• Automatic capture — with a repository linked, pushes, deployments, releases and CLI syncs are recorded without a command.

# npm
npm install -g @pulse/cli

# pnpm
pnpm add -g @pulse/cli

# yarn
yarn global add @pulse/cli

pulse --version
# pulse/1.0.0 darwin-arm64 node-22.11.0

pulse login authenticates this machine against your Pulse identity. It prints a code, opens your browser, and waits for you to confirm that the code matches. Nothing is typed into the terminal — the CLI never sees your credentials, and you never paste a token you had to generate by hand.

pulse login

Pulse — authenticate this machine

  Verification code:  QFTM-9042

  Open  https://pulse.dev/activate  and confirm the code above.
  Waiting for confirmation…

✓ Authenticated as @aria (Aria Nakamura)
  Credential written to ~/.pulse/credentials.json

A pipeline cannot open a browser, so it authenticates with a token from the environment. The CLI reads PULSE_TOKEN before it reads the credential file, so no login step is needed in CI at all.

# .github/workflows/deploy.yml
- name: Record the deployment
  env:
    PULSE_TOKEN: ${{ secrets.PULSE_TOKEN }}
  run: pulse deploy --environment production --version ${{ github.sha }}

1. Install the CLI once per machine.
2. Run pulse login once per machine.
3. Run pulse init and pulse link once per project.
4. Add PULSE_TOKEN to your CI secrets and pulse deploy to your pipeline.
5. From then on, the only CLI commands you type by hand are pulse event, pulse status and pulse logs.

A complete first-run on a new machine, from empty to recording.

npm install -g @pulse/cli
pulse login

cd ~/code/atlas-gateway
pulse init --project atlas-gateway --org northwind
pulse link github.com/northwind/atlas-gateway

pulse status

{
  "version": 1,
  "project": "atlas-gateway",
  "organization": "northwind",
  "repository": "github.com/northwind/atlas-gateway",
  "defaults": {
    "visibility": "public"
  }
}

• Install globally. The CLI is a developer tool, not a project dependency, and pinning it per project buys you nothing.
• Log in once per machine and leave it. The credential is long-lived on purpose — an expiring token that forces a re-login mid-incident is how incidents go unrecorded.
• Use PULSE_TOKEN in CI and a browser login on laptops. Never copy a laptop credential into a pipeline.
• Commit pulse.json. It is configuration, and everyone on the project should be recording into the same project.

• Adding @pulse/cli to a project's dependencies. It is a global tool; installing it per project creates version drift across a team for no benefit.
• Committing ~/.pulse/credentials.json, or pasting a token into pulse.json. Both are credentials in a repository.
• Running pulse login in CI. It will wait for a browser confirmation that will never come. Set PULSE_TOKEN instead.
• Assuming logout deletes your data. pulse login --logout removes a credential from a machine. It does not touch your events, proofs or Build Cred.

• The CLI requires Node 20 or newer.
• You can be logged in on many machines at once. Each holds its own credential and can be revoked independently.
• The CLI never reads your source code. It reads pulse.json and the git metadata it needs to identify a commit — nothing else leaves your machine.
• Using the CLI is optional. Events can be authored in the Engineering Workspace in the browser — but automatic capture and deployment metadata require it.