PulseGuard CLI

Set up and manage your whole PulseGuard monitoring environment from the terminal - and let an AI agent (Claude in your editor) drive it.

📖 Documentation: https://docs.ipulse.one/en/pulseguard/cli

The CLI wraps PulseGuard's existing MCP tools and /api/v1 REST API behind a friendly, colourful command surface, with machine-readable JSON output so an agent can read results back and act on them in a fix loop.

▰ PulseGuard CLI

USAGE
  pulseguard <command> [subcommand] [options]   (alias: pg)

Install

The CLI is a self-contained, zero-runtime-dependency package. Run it without installing via your package manager's runner:

bunx @ipulsehq/pulseguard-cli --help
# or
npx  @ipulsehq/pulseguard-cli --help

…or install it globally as pulseguard / pg:

bun add -g @ipulsehq/pulseguard-cli
pulseguard --help

Authenticate

Login uses the iPulse OAuth 2.0 Authorization Code + PKCE loopback flow. It opens your browser, you approve, and tokens are stored under ~/.pulseguard/.

pulseguard login                 # pick an environment, then OAuth in the browser
pulseguard whoami                # show who you are signed in as
pulseguard logout

The OAuth session covers every command. The only thing that needs a PulseGuard API key is the generic pulseguard api REST escape hatch. Create one in the dashboard (Settings → API Keys), then:

pulseguard login --api-key pg_xxx     # store an API key for `pulseguard api`
# or set PULSEGUARD_API_KEY in your environment

Choose an environment

The CLI operates against a selected environment:

pulseguard env ls                # list environments + which is active
pulseguard switch production     # or: local
pulseguard switch --api-url http://localhost:5000   # custom endpoint

Overrides per-invocation: --env <id>, --api-url <url>, or the PULSEGUARD_API_URL / PULSEGUARD_ENV environment variables.

Choose an organization

If your account has multiple organizations (workspaces), pick which one commands operate against. The choice is stored per environment and applied automatically as --org on every command:

pulseguard org                   # interactive picker (lists workspaces)
pulseguard org ls                # list workspaces + which is active
pulseguard org switch "Acme"     # by name, id, or 1-based index
pulseguard org current           # show the active workspace
pulseguard org clear             # revert to the primary workspace

Overrides per-invocation: --org <id>, or the PULSEGUARD_ORG environment variable. With no organization selected, the API uses your primary workspace.

Commands

| Command | What it does | | --- | --- | | doctor | Diagnose connectivity, auth, API key & MCP tool access | | setup | Apply a whole environment from a plan (services, flow monitors, status pages, security) | | status | Dashboard summary (domains / services / devices / incidents) | | domains [ls\|summary <domain>] | Domain status, uptime & 30-day summary | | services [ls\|create\|check] | Service monitors (TCP/HTTP/DNS/SMTP/IMAP/DB/…) | | synthetic <ls\|get\|create\|update\|run\|results\|toggle\|rm> | Full synthetic-flow lifecycle | | status-pages <ls\|get\|create\|add-domain\|add-service\|add-device\|rm> | Status pages | | incidents | List incidents | | security <scan\|get\|summary\|recommendations\|vulnerabilities> | Security scans & findings | | accessibility <run\|results\|pagespeed> | Accessibility & SEO tests (alias a11y) | | projects <ls\|get\|create\|update\|rm\|link\|unlink> | Group resources into projects | | reports | Roll-up report (totals + per-resource breakdown) | | notifications [test <channel>] | Notification preferences & test delivery | | mcp tools | List every MCP tool the server exposes | | mcp call <tool> --args '{…}' | Call any MCP tool directly | | init [editor] | One-shot: wire MCP + install agent guidance for your editor | | mcp install [client] | Add the PulseGuard MCP server to an editor/agent | | api <METHOD> <path> --data '{…}' | Call any /api/v1 REST endpoint (API key) | | skills add [client] / rules add | Install the agent guide (Claude Code/Cursor/Windsurf/Copilot/AGENTS.md) | | completion <bash\|zsh\|fish> | Print a shell completion script |

Add --json to any command for clean, parseable output (status/log lines go to stderr; only the result document goes to stdout). Other global flags: --env, --api-url, --debug (trace HTTP to stderr), --quiet, --no-color, --timeout <seconds>.

Exit codes

Stable codes so scripts and agents can branch on the outcome:

| Code | Meaning | | Code | Meaning | | --- | --- | --- | --- | --- | | 0 | ok | | 4 | not found | | 1 | error | | 5 | conflict / already exists | | 2 | usage | | 6 | forbidden / scope | | 3 | auth (run login) | | 7 | network / timeout |

In --json mode a failure prints { "ok": false, "error": "…", "code": N, "hint": "…" }.

Set up a whole environment in one shot

setup applies a declarative plan and reads results back - ideal for an agent loop. It creates service monitors, synthetic flow monitors (created, run, and results fetched), status pages and security scans; each step is isolated so one failure doesn't abort the rest.

pulseguard setup --example > plan.json   # learn the schema
pulseguard setup --file plan.json --json # apply; report lists pass/fail per step

Scaffold a starter flow monitor to drop into the plan (or create directly):

pulseguard synthetic scaffold --out flow.json
pulseguard synthetic create --file flow.json --json
pulseguard synthetic run <flowId> --json
pulseguard synthetic results <flowId> --json

Example: set up monitoring for an app

pulseguard login
pulseguard services create --name "API health" --protocol https \
  --host api.example.com --path /health --json
pulseguard synthetic create --file login-flow.json --json
pulseguard synthetic run <flowId> --json
pulseguard synthetic results <flowId> --json
pulseguard status-pages create --name "Status" --slug status --json
pulseguard security scan <domainId> --json
pulseguard status --json

Make a project agent-ready (works for Cursor, Claude Code, etc.)

init is the one-shot: it wires the PulseGuard MCP server into your editor's config and installs the agent guidance (skill / rules), so the agent immediately knows how to drive PulseGuard.

pulseguard init                 # interactive editor picker
pulseguard init cursor          # .cursor/mcp.json + .cursor/rules/pulseguard.mdc
pulseguard init claude-code     # ./.mcp.json + .claude/skills/pulseguard/SKILL.md
pulseguard init vscode          # .vscode/mcp.json + .github/copilot-instructions.md
pulseguard init claude-desktop  # mcp-remote bridge + AGENTS.md

After running it, ask the agent "set up PulseGuard monitoring for this app and run the login flow" and it operates PulseGuard directly.

Just the MCP server

mcp install wires only the remote MCP server (<api>/mcp, OAuth) into a client config:

pulseguard mcp install                 # interactive picker
pulseguard mcp install claude-code     # writes ./.mcp.json
pulseguard mcp install cursor          # writes ~/.cursor/mcp.json (type: http)
pulseguard mcp install vscode          # writes ./.vscode/mcp.json (type: sse)
pulseguard mcp install claude-desktop  # mcp-remote stdio bridge
pulseguard mcp install --print         # just print the snippet, change nothing

Just the agent guidance (skill / rules)

skills add (alias rules add) installs the PulseGuard guide in the format each agent expects. The content is identical everywhere (defined once); only the file shape differs.

pulseguard skills add                  # interactive picker
pulseguard skills add cursor           # .cursor/rules/pulseguard.mdc
pulseguard skills add claude-code      # .claude/skills/pulseguard/SKILL.md
pulseguard skills add windsurf         # .windsurf/rules/pulseguard.md
pulseguard skills add copilot          # .github/copilot-instructions.md (merged section)
pulseguard skills add agents           # ./AGENTS.md (merged section)
pulseguard skills add --all            # all of the above

Shared files (Copilot, AGENTS.md) get a <!-- pulseguard:start -->…<!-- pulseguard:end --> section that is updated in place on re-run, so your own content is preserved.

Configuration & files

| Path | Purpose | | --- | --- | | ~/.pulseguard/config.json | Selected environment (non-secret) | | ~/.pulseguard/auth.json | OAuth tokens / API keys, per environment (mode 0600) |

Override the directory with PULSEGUARD_CONFIG_DIR (handy for CI).

Honoured environment variables: PULSEGUARD_API_URL, PULSEGUARD_APP_URL, PULSEGUARD_ENV, PULSEGUARD_API_KEY, PULSEGUARD_CONFIG_DIR, NO_COLOR, FORCE_COLOR.

Develop

bun run dev -- --help      # run from source (apps/cli)
bun run build              # bundle to dist/ via tsup
bun run typecheck          # tsc --noEmit
bun test                   # unit tests

Built on Node's standard library only (no runtime dependencies): fetch for HTTP, node:crypto for PKCE, node:http for the OAuth loopback server, and a tiny ANSI/prompt layer for the UI.