Commands

The CLI has seven commands beyond login and deploy. Each maps to exactly one thing you do to your engineering record: create a project, give it a source, record judgment, inspect what was captured, read the timeline, manage configuration, and reconcile what happened offline.

The commands exist to make recording cost nothing at the moment engineering happens. Anything that could be captured from a source is not a command at all — which is why this list is short, and why there is no command to create a PUSH.

A CLI grows by accretion unless someone refuses. Every command here had to justify itself against one test: does it capture something Pulse cannot get from a source, or does it answer a question you have while your hands are on the keyboard? Commands that only wrapped the web UI were cut. There is no pulse profile, no pulse org create, no pulse search — those are things you do in a browser, and duplicating them in a terminal would have doubled the surface without recording a single additional event.

• Configuration resolution — the CLI walks up from the current directory to find pulse.json. Flags override the file; the file overrides defaults.
• Authentication resolution — PULSE_TOKEN is read before ~/.pulse/credentials.json, so CI never needs a login step.
• Recording is append-only — there is no pulse edit and no pulse delete. A correction is a new event.
• Machine-readable output — --json is supported wherever output is data, so the CLI composes with scripts.

Every command follows the same shape. The reference below is the whole surface.

Creates a Pulse project and writes pulse.json. Run it once per project, from the repository root — the CLI resolves configuration by walking up from the current directory, so a pulse.json in a subdirectory will quietly apply to only part of your work.

pulse init --project atlas-gateway --org northwind

# Or answer the prompts
pulse init

Binds a project to the repository that will verify it. This is the single most consequential command in the CLI: until a project has a source, its events cannot be attested above L1, and events already recorded are not retroactively upgraded.

pulse link github.com/northwind/atlas-gateway

# Confirm what the project is linked to
pulse link --status

# Repoint a project at a different repository
pulse link github.com/northwind/atlas-gateway --replace

Records an engineering event that no machine can infer. It takes the kind as a subcommand: block, unlock or pivot. There is no pulse event push — execution is captured from source, never authored.

# Something is broken and engineering is on it
pulse event block \
  --title "Connection-pool exhaustion under deploy stampede" \
  --technology postgres \
  --description "Rolling deploys open a new pool per replica before old replicas drain."

# It is resolved, and this is what did it
pulse event unlock \
  --resolves evt_atlas_pool_block \
  --title "Resolved with a shared pooler and drain gate"

# A decision was reversed, and this is the reasoning
pulse event pivot \
  --title "Moved edge cache from LRU to segmented W-TinyLFU" \
  --description "LRU thrashed under the recommendation workload's scan pattern."

Answers the only question you actually have day to day: is Pulse capturing my work? It prints the resolved project, the link and its verification sources, the authenticated identity, and the events recently captured with their trust levels.

pulse status
pulse status --verbose

Project       atlas-gateway (northwind)
Repository    github.com/northwind/atlas-gateway   ✓ linked      (source: github)
Pipeline      GitHub Actions                       ✓ reporting   (source: ci)
Identity      @aria                                ✓ authenticated

Recent events
  UNLOCK  Resolved connection-pool exhaustion   verified · L3   2h ago
  BLOCK   Connection-pool exhaustion            verified · L2   6h ago
  PUSH    Deployed v2.4.0 to production         verified · L3   1d ago

3 events captured · 0 pending

Reads the timeline from the terminal. It is a read of a projection — the same record the project page shows — filtered the way you would filter a log.

# Everything on this project in the last week
pulse logs --since 7d

# Only unresolved incidents
pulse logs --kind BLOCK --unresolved

# One engineer's record on this project, as JSON
pulse logs --author @aria --json

Reads and writes pulse.json without you opening it. Every value it manages is project configuration and is safe to commit; there is no path by which config can hold a credential.

# Read the resolved configuration
pulse config list

# Read one value
pulse config get visibility

# Change a default
pulse config set defaults.visibility masked

# Point the project at an organization
pulse config set organization northwind

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

Reconciles local execution that Pulse has not yet seen — the case that matters is a machine that was offline. Events are recorded with the time they occurred, not the time they were synced, so a late sync lands in the right place on the timeline and cannot be used to rewrite history.

pulse sync

# See what would be sent, without sending it
pulse sync --dry-run

The full lifecycle of a project through the CLI, in the order you actually meet it.

1. pulse login — once, on this machine.
2. pulse init — once, at the repository root.
3. pulse link — immediately after init, so verification is live before you record anything.
4. pulse deploy — in CI, on every deployment.
5. pulse event block / unlock / pivot — when engineering produces something a machine cannot infer.
6. pulse status and pulse logs — whenever you want to know what the record says.

A full incident, worked entirely from the terminal.

# 02:41 — the gateway is 503ing during deploys
pulse event block \
  --title "Connection-pool exhaustion under deploy stampede" \
  --technology postgres \
  --description "Rolling deploys open a new pool per replica before the old replicas drain. Postgres hits max_connections and the gateway 503s for ~90s per deploy."

# 04:55 — check what else has broken here before
pulse logs --project atlas-gateway --kind BLOCK --since 90d

# 06:10 — the fix is out; CI captured the deployment as a PUSH on its own
pulse event unlock \
  --resolves evt_atlas_pool_block \
  --title "Resolved connection-pool exhaustion with a shared pooler and drain gate" \
  --description "Replicas now sit behind PgBouncer in transaction mode, so pool size is decoupled from replica count. New-replica readiness is gated on old-replica drain."

# 06:12 — confirm the record
pulse status

• Why can I not record a PUSH? Because execution must be provable. A hand-written PUSH would be a self-report, and self-reports are exactly what Pulse exists to replace. If deployments are missing, check pulse link --status.
• Can I edit or delete an event? No. The log is append-only. Record a new event — a PIVOT, or a corrected UNLOCK — and both remain visible. This is the property that makes the record worth reading.
• Do I need the CLI? Not strictly. BLOCK, UNLOCK and PIVOT can be authored in the Engineering Workspace. Automatic capture and deployment metadata do require it.
• Does the CLI read my source code? No. It reads pulse.json and the git metadata needed to identify a commit. Nothing else leaves the machine.
• Why is my event L1 when the repository is linked? Verification is applied at capture time. Events recorded before the link was made keep the level they were minted at.
• Can I run it in a monorepo? Yes. Configuration resolves by walking up from the current directory, so a pulse.json per package records each into its own project.
• What happens if I lose my laptop? Run pulse login --logout from another machine to revoke that credential. Your events, proofs and Build Cred are unaffected.

• Run pulse link the moment you run pulse init. The gap between them is the window in which your events are minted at a lower trust level.
• Put pulse deploy in the pipeline, never in a personal shell script. A deployment reported by CI attests at L3; the same one announced from a laptop cannot.
• Use pulse logs --unresolved before standup. It is the shortest honest answer to 'what is broken'.
• Prefer --resolves over describing the link in prose. The edge is what produces the arc and the knowledge artifact; the sentence produces nothing.

• Running pulse init in a subdirectory. Configuration resolves upward, so the project silently applies to only part of the repository.
• Every teammate running pulse init, producing four projects with the same name and four fragmented timelines.
• Recording an UNLOCK without --resolves. It closes nothing, produces no artifact, and earns nothing in Resolution.
• Running pulse login in CI and waiting for a browser confirmation that will never arrive. Set PULSE_TOKEN.
• Reaching for a command to fix a bad event. There isn't one, and there will not be — append a correction.

• Every command accepts --help, and --json wherever output is data.
• Flags override pulse.json; pulse.json overrides defaults. There is no global user-level project config, on purpose.
• pulse sync is rarely needed by hand. It exists for the offline case and for pipelines that batch their reporting.
• The CLI is versioned independently of the platform. pulse --version reports the CLI; the verification engine version is recorded on each proof.