CLI Reference

What is Pulse CLI?

Pulse CLI (pulse) captures AI-agent activity as structured spans and ships it to your Pulse server.

It supports two workflows:

local managed Pulse: the CLI starts and manages pulse-server for you
remote/shared Pulse: the CLI connects to an already running Pulse instance

Install

Recommended (installs both pulse-server and pulse):

curl -fsSL https://raw.githubusercontent.com/EK-LABS-LLC/trace-service/main/scripts/install.sh | bash -s -- pulse-server

CLI-only installer:

curl -fsSL https://raw.githubusercontent.com/EK-LABS-LLC/trace-cli/main/install.sh | sh

From source:

git clone https://github.com/EK-LABS-LLC/trace-cli
cd pulse-trace-cli
make install

Re-running either installer upgrades in place. It replaces the installed binaries and keeps your existing ~/.pulse config and local data.

Getting started

Local managed Pulse

Use this when Pulse should run on your machine.

pulse setup --local
pulse up
pulse status

Daily use:

pulse up starts pulse-server in the background
pulse logs --follow tails the managed server log
pulse down stops the managed server

Remote/shared Pulse

Use this when a Pulse server already exists at a URL you can reach.

pulse connect \
  --api-url https://pulse.example.com \
  --api-key pulse_sk_... \
  --project-id my-project

Then verify:

pulse status

pulse connect saves a remote config and installs hooks locally. It does not start a server.

Updating

Local managed Pulse

Re-run the trace-service installer:

curl -fsSL https://raw.githubusercontent.com/EK-LABS-LLC/trace-service/main/scripts/install.sh | bash -s -- pulse-server

This updates pulse-server, dashboard assets, and the pulse CLI while preserving ~/.pulse data.

Remote/shared Pulse users

If you only use the CLI locally, re-run the CLI installer:

curl -fsSL https://raw.githubusercontent.com/EK-LABS-LLC/trace-cli/main/install.sh | sh

Command reference

Command	Description
`pulse setup`	Bootstrap a local or remote Pulse account/project and save config
`pulse up`	Start the managed local Pulse server in the background
`pulse down`	Stop the managed local Pulse server
`pulse restart`	Restart the managed local Pulse server
`pulse logs`	Show or follow managed local server logs
`pulse dashboard`	Open the current Pulse dashboard URL
`pulse init`	Deprecated alias for `pulse connect`
`pulse connect`	Configure a remote Pulse instance and install hooks
`pulse install-hooks`	Install Pulse hooks without changing config (requires existing config)
`pulse disconnect`	Remove all Pulse hooks from all agents
`pulse status`	Show mode, connectivity, server state, and hook status
`pulse emit <type>`	Send a span (used by hooks, not by users)

`pulse setup`

Local bootstrap:

pulse setup --local

Fully non-interactive:

pulse setup \
  --api-url http://localhost:3000 \
  --name "Your Name" \
  --email you@example.com \
  --password "change-me" \
  --project-name "My Project"

Remote account bootstrap against an existing server:

pulse setup --api-url https://pulse.example.com --no-start-server

Show the full API key in setup output:

pulse setup --local --show-api-key

After local setup, use pulse up for normal day-to-day startup.

`pulse up`

pulse up

# Start and open the dashboard
pulse up --open

Starts pulse-server in the background, waits for /health, and prints the dashboard URL, PID, and log path.

`pulse down`

pulse down

Stops the managed local pulse-server.

`pulse restart`

pulse restart

# Restart and open the dashboard
pulse restart --open

`pulse logs`

# Show the most recent lines
pulse logs

# Follow logs continuously
pulse logs --follow

# Tail more lines before following
pulse logs --lines 300 --follow

`pulse dashboard`

# Open the configured dashboard
pulse dashboard

# Print the URL without opening a browser
pulse dashboard --no-open

In local mode, this opens the local dashboard served by pulse-server. In remote mode, it opens the configured remote Pulse URL.

`pulse init`

# Deprecated alias for `pulse connect`
pulse init

`pulse connect`

pulse connect \
  --api-url https://pulse.example.com \
  --api-key pulse_sk_... \
  --project-id my-project

Interactive prompts work too:

pulse connect

This:

saves a remote-mode config to ~/.pulse/config.toml
validates /health by default
installs hooks into detected agents unless --no-hooks is set

`pulse install-hooks`

pulse install-hooks

Installs Pulse hooks into detected agents without modifying your Pulse configuration. Use this when you are already connected to a Pulse server but don’t have hooks installed.

This command:

validates that ~/.pulse/config.toml exists with valid api_url, api_key, and project_id
prompts to run pulse connect if config is missing or incomplete
installs hooks for all detected tools (Claude Code, OpenCode, OpenClaw)

Use pulse connect when you need to both connect to a server AND install hooks.

`pulse disconnect`

pulse disconnect

Removes Pulse-managed hooks and plugins while leaving unrelated agent configuration alone.

`pulse status`

pulse status

Shows:

current mode (local or remote)
configured API URL and project
local server PID, health, and log path in local mode
remote connectivity in remote mode
hook status for each detected agent

`pulse emit <event_type>`

Internal command called by integrations. Usually not called directly.

echo '{"session_id":"abc","tool_name":"Bash"}' | pulse emit pre_tool_use

Hot-path guarantees:

always exits with code 0
no stdout or stderr output
2-second HTTP timeout

Configuration

Config file: ~/.pulse/config.toml

Local mode example:

mode = "local"
api_url = "http://localhost:3000"
project_id = "my-project"

Remote mode example:

mode = "remote"
api_url = "https://pulse.example.com"
api_key = "pulse_sk_..."
project_id = "my-project"

Field	Description
`mode`	`local` or `remote`
`api_url`	Base URL of the current Pulse server
`api_key`	Project API key used in remote mode
`project_id`	Project identifier attached to spans

Environment variables

Variable	Description
`PULSE_DEBUG`	Set `1` to log raw integration payloads
`PULSE_DEBUG_LOG`	Override debug log path (`~/.pulse/debug.log` by default)

Events and span model

Pulse integrations emit these normalized event types:

Event	Kind	Description
`session_start`	`session`	Agent session begins
`session_end`	`session`	Agent session ends
`stop`	`session`	Agent stops execution
`user_prompt_submit`	`user_prompt`	User sends prompt
`assistant_message`	`llm_response`	Assistant response
`pre_tool_use`	`tool_use`	Tool call about to run
`post_tool_use`	`tool_use`	Tool call succeeded
`post_tool_use_failure`	`tool_use`	Tool call failed or was interrupted
`subagent_start`	`agent_run`	Child agent started
`subagent_stop`	`agent_run`	Child agent finished
`notification`	`notification`	Agent notification event

Example span payload:

{
  "span_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "abc-123",
  "timestamp": "2026-02-19T14:30:00.000Z",
  "source": "claude_code",
  "kind": "tool_use",
  "event_type": "pre_tool_use",
  "status": "success",
  "tool_name": "Bash",
  "tool_use_id": "tool_abc",
  "tool_input": { "command": "ls" },
  "metadata": {
    "cli_version": "0.1.0",
    "project_id": "my-project"
  }
}

Additional fields such as tool_response, error, model, agent_name, and cwd are included when available.

Agent integrations at a glance

Integration	Detection path	Pulse-managed files
Claude Code	`~/.claude/settings.json` or `~/.claude/settings.local.json`	`hooks` entries in `settings.json` or `settings.local.json`
Opencode	`~/.config/opencode/`	`~/.config/opencode/plugin/pulse-plugin.ts`
OpenClaw	`~/.openclaw/`	`~/.openclaw/hooks/pulse-hook/`

Pulse only modifies Pulse-owned entries and files. Other hooks and plugins are preserved.

Troubleshooting

`Config missing`

For local mode:

pulse setup --local

For remote mode:

pulse connect --api-url https://pulse.example.com --api-key pulse_sk_... --project-id my-project

Local server not running

pulse up

Then inspect logs:

pulse logs --follow

Agent not detected

Pulse detection paths:

Claude Code: ~/.claude/settings.json or ~/.claude/settings.local.json (preferred)
Opencode: ~/.config/opencode/
OpenClaw: ~/.openclaw/

Hooks installed but no spans

Run pulse status and confirm Pulse is reachable.
Enable debug logs with PULSE_DEBUG=1.
Check ~/.pulse/debug.log for incoming payloads.
Verify API URL, API key, and project ID.

Stale integration plugin

After CLI upgrades, run:

# If already connected to a server:
pulse install-hooks

# If not yet connected:
pulse connect

Architecture

Claude Code hooks / Opencode plugin / OpenClaw hook
          -> pulse emit <event_type>
          -> normalize payload into span
          -> POST /v1/spans/async (2s timeout)
          -> Pulse server

Design choices:

non-blocking hooks
silent failure mode for integrations (pulse emit exits 0)
idempotent connect and disconnect behavior
no runtime npm downloads for plugin content

Building from source

make build
make release
make test
make install

Running E2E tests

Requires Docker or Podman and a reachable Pulse server.

make e2e

# Individual suites
make e2e-claude
make e2e-claude-tools
make e2e-opencode
make e2e-opencode-tools

Integration docs

Claude Code

Opencode

OpenClaw