Getting Started

This guide takes you from nothing to a working engineering record: sign in, complete onboarding, install the CLI, link a repository, and watch your first event arrive verified. It assumes no prior knowledge of Pulse.

Setup has two halves. The first is done once, in the browser: you authenticate, choose which repositories Pulse may verify, and join or create an organization. The second is done once per project, from your terminal: you initialize a Pulse project and link it to its repository.

After that, nothing is routine. Execution is captured for you. The only thing you do by hand is record judgment — the blocks, resolutions and reversals a machine cannot infer.

The goal of this page is not to get you clicking through a wizard. It is to leave you with three things that make everything else in Pulse work: an authenticated identity, at least one verification source connected, and one project whose timeline is live.

You may reasonably ask why Pulse needs a repository connection at all when you could just tell it what you built. That is exactly the thing we will not accept. A record that can be typed in is a record that can be invented, and a reputation derived from invented records is worth nothing. So the setup asks for a verification source before it asks for anything else — because without one, Pulse can host your claims but cannot stand behind them.

• Identity — your Pulse account. Owned by you, not by an employer, and it survives leaving one.
• Verification source — a system Pulse can check against, such as a linked GitHub repository or a deployment pipeline.
• Project — the execution container your events belong to. Usually one per repository.
• Organization — an optional container that groups projects and members. You can work without one.

Open Pulse and continue with GitHub. Existing accounts sign in; new accounts are created on first authorization. There is no separate password to manage.

First-time accounts are taken through a six-step flow. It exists to establish the verification sources Pulse will rely on from then on.

1. Welcome — what Pulse records, and what it will not.
2. Connect GitHub — authorize the integration that lets Pulse observe execution.
3. Choose repositories — select which repositories Pulse may verify against. Nothing outside this list is ever read.
4. Choose your organization — join an existing organization or continue as an individual.
5. Complete your profile — handle, name, role, and headline. Your handle is your permanent address: /@aria.
6. Done — your identity is live and your first project can be initialized.

# Install globally
npm install -g @pulse/cli

# Confirm the install
pulse --version

# Authenticate this machine against your Pulse identity
pulse login

pulse login opens your browser, asks you to confirm the code shown in the terminal, and writes a token to ~/.pulse/credentials.json. You authenticate a machine once, not a session.

Run these from the root of the repository you want to record. init creates the project and writes pulse.json; link binds it to the repository that will verify it.

cd ~/code/atlas-gateway

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

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

Commit pulse.json. It is project configuration, not a secret — it contains no token and is meant to be shared with everyone who works on the repository.

Once setup is done, the loop is short and mostly passive.

1. Write and ship code exactly as you did before.
2. Pushes, releases and deployments appear on the project timeline without you doing anything.
3. When you get stuck on something real, record a BLOCK.
4. When you resolve it, record an UNLOCK that references the BLOCK.
5. Check pulse status when you want to confirm what has been captured.

Ship a deployment and confirm it landed as a verified event. This is the fastest way to prove your setup is correct end to end.

# Record a production deployment
pulse deploy --environment production --version v2.4.0

# Confirm it was captured and verified
pulse status

Project       atlas-gateway (northwind)
Repository    github.com/northwind/atlas-gateway  ✓ linked
Identity      @aria                               ✓ authenticated

Recent events
  PUSH    Deployed v2.4.0 to production        verified · L3   2m ago
  PUSH    Shipped adaptive rate limiter        verified · L3   1d ago

2 events captured · 0 pending

• Run pulse init from the repository root. The CLI resolves configuration by walking up from the current directory, and a pulse.json in the wrong place is the most common source of confusion later.
• Link the repository immediately after init. A project with no source cannot be verified above L1, and events recorded in that window stay at the lower trust level.
• Commit pulse.json. Every contributor should be recording into the same project, not creating their own.
• Use PULSE_TOKEN in CI rather than copying credentials from a laptop.

• Skipping the repository step in onboarding, then wondering why no events appear. Pulse only observes repositories you explicitly selected.
• Running pulse init once per developer instead of once per project. If the project already exists, use pulse link — do not create a second one.
• Committing ~/.pulse/credentials.json. It is a machine credential and belongs in your home directory, never in a repository.
• Expecting historical activity to backfill. Pulse begins recording when the link is made; it does not import your repository's past.

• Disconnecting GitHub stops future verification but does not delete past events. Existing proofs remain valid and Build Cred already earned is retained.
• You can belong to no organization at all. Individual projects are first-class, and Build Cred does not require an employer.
• The CLI is not required to use Pulse — events can be recorded in the Engineering Workspace in the browser — but automatic capture and deployment metadata do require it.