agentpulse CLI

The AgentPulse developer CLI — connect to your dev-orgs, scaffold apps, and deploy code/schema/seed into a dev-org's own instance. Published on public npm as @agentpulselabs/cli; the command you type is agentpulse (short alias: ap).

Install

npm install -g @agentpulselabs/cli
agentpulse --version

Update later with npm install -g @agentpulselabs/cli@latest.

Prerequisites

• Node 18+.
• git — required for app publish and app deploy --code (packaging archives a git ref).
• Atlas is NOT required — the CLI downloads a pinned Atlas binary on first app deploy of objects (schema) and caches it under ~/.cache/agentpulse/. Code- and seed-only deploys need nothing extra.

First run

agentpulse login --url https://<your-platform-url>   # browser OAuth (PKCE); connects the CLI to your team
agentpulse whoami                                     # confirm identity + connected platform + default dev-org

Credentials are stored per-profile in ~/.config/agentpulse/config.json (mode 0600) — same model as the gh/sf CLIs. agentpulse logout removes them.

Commands

Auth

| Command | What it does | |---|---| | agentpulse login --url <platform> | Browser OAuth login; connects the CLI to your platform + team. | | agentpulse logout | Remove the stored credentials for a profile. | | agentpulse whoami | Show who you're logged in as + the connected platform + default dev-org. |

Dev-orgs

| Command | What it does | |---|---| | agentpulse org list | List your team's dev-orgs. | | agentpulse org use <slug> | Set + connect the default dev-org (mints a dev-org-scoped token). | | agentpulse org open | Open the target dev-org in your browser (authenticated Cloud Run proxy). | | agentpulse org status | Show a dev-org's status, reach details, and connection state (the sf org display analog). |

Schema (read-only inspection)

| Command | What it does | |---|---| | agentpulse schema describe | Describe a dev-org's live table schema — columns, types, PK/FK, uniques, indexes, enums (the sf sobject describe analog). | | agentpulse schema diff | Show the pending schema delta (local objects/ vs the dev-org's live schema) without applying — read-only. | | agentpulse schema pull | Reconstruct local objects/ JSON from a dev-org's live schema — the read-only inverse of app deploy. | | agentpulse schema export | Export the live schema as a Markdown data dictionary (stdout or --out file). | | agentpulse schema graph | Render the live schema as a Mermaid ERD (stdout or --out file). |

Apps

| Command | What it does | |---|---| | agentpulse app new | Scaffold a new app project (or register an existing folder). | | agentpulse app validate | Run the platform gates against your app (the --check-only analog). | | agentpulse app deploy | Push objects / seed / code into your dev-org — the inner loop. | | agentpulse app publish | Build + publish a versioned package → install URL. | | agentpulse app install | Install a published app into your team. | | agentpulse app versions | List an app's published versions + statuses. |

Diagnostics

| Command | What it does | |---|---| | agentpulse doctor | Diagnose your environment and readiness — Node, Atlas, login, target dev-org, app project (the sf doctor analog). |

Plugins

The CLI is extensible via oclif plugins — opt-in commands you install into agentpulse.

| Command | What it does | |---|---| | agentpulse plugins | List installed plugins. | | agentpulse plugins install <pkg> | Install a plugin (adds its commands). | | agentpulse plugins uninstall <pkg> | Remove a plugin. |

The pulse build-discipline plugin (contract-enforced Discovery → Stories → Architecture → Build → Deliver):

# Public npm package under the @agentpulselabs org — no extra auth.
agentpulse plugins install @agentpulselabs/cli-plugin-pulse
agentpulse pulse --help        # start · next · submit · gate · verify · status

Prefer an interactive/agent runtime (Cursor/Codex/Claude)? The same discipline ships as the pulse-mcp MCP server in the @agentpulselabs/pulse package — point your agent's MCP config at it instead of the CLI.

Pulse is developed in its own repo — github.com/ashishcloud/agentpulse-pulse (both @agentpulselabs/pulse and @agentpulselabs/cli-plugin-pulse).

Run agentpulse <command> --help for flags on any command.

The inner loop (app deploy)

From inside an app project (after agentpulse org use <slug>):

agentpulse app deploy --metadata object:agents --dry-run   # preview the schema delta for one object
agentpulse app deploy --source seed                        # push just the seed manifests
agentpulse app deploy --source code                        # push app code → hot-reloads the dev-org (~seconds)
agentpulse app deploy --all                                # objects + seed + code

• objects → the CLI compiles a scoped schema delta locally (Atlas, auto-downloaded) and the dev-org applies it — one ALTER TABLE for one added field, never a whole-schema diff.
• code → bundled + hot-reloaded into the dev-org behind a process boundary (a bad build can't take the dev-org down; it keeps serving the previous version).
• --dry-run previews without applying; --force allows a destructive schema change.

deploy (my dev-org, instant, unversioned) is distinct from publish (a versioned package for other tenants) — deploy is the iterate loop, publish is the release.

Notes

• Using app deploy / org requires a dev-org, which requires your team to be entitled to dev-orgs on the platform. If org list is empty, ask your platform admin for a dev-org.
• The typed command (agentpulse) is independent of the package name (@agentpulselabs/cli).