@hs-x/cli

The command-line tool for HS-X, a type-safe HubSpot app framework that deploys to Cloudflare Workers. Installing this package puts the hs-x command on your PATH: it scaffolds projects, runs the local dev loop, and deploys to your own HubSpot developer app and your own Cloudflare account.

Install

npm i -g @hs-x/cli
hs-x --version

Node 20+ and Bun can both run it. The npm package is @hs-x/cli; the installed command is hs-x. If you prefer not to install anything globally, every command also works through bunx @hs-x/cli <command>.

Thirty seconds

hs-x init deal-tagger     # scaffold a project (default template: workflow action)
cd deal-tagger
bun install
hs-x connect              # bind a HubSpot developer account and a Cloudflare account
hs-x dev                  # local dev loop
hs-x deploy               # deploy to your HubSpot app and your Cloudflare account

The CLI works direct-to-HubSpot out of the box. You provide the HubSpot and Cloudflare credentials, the CLI talks to both platforms directly, and nothing requires an HS-X platform account. The control plane, dashboard, and billing are opt-in: hs-x login authenticates an HS-X account and hs-x link attaches an already-deployed project to it.

Deployed Workers run in your Cloudflare account, and the generated .hs-x/alchemy.run.ts (checked into your repo) describes the Cloudflare resources your app owns — the app keeps running even if you stop using HS-X.

Commands

Grouped the way hs-x help prints them.

Start:

| Command | What it does | | --- | --- | | hs-x init [name] | Create a new HS-X project | | hs-x connect | Link this project to HubSpot and Cloudflare | | hs-x doctor | Diagnose local setup | | hs-x check | Validate project source |

Develop:

| Command | What it does | | --- | --- | | hs-x dev | Start the local dev server | | hs-x api <path> | Call HubSpot or the HS-X control plane | | hs-x flags | Manage feature flags | | hs-x migrate | Migrate legacy HubSpot apps |

Deploy:

| Command | What it does | | --- | --- | | hs-x deploy | Deploy the project | | hs-x promote | Promote a deploy to an environment | | hs-x rollback | Roll back an environment | | hs-x routes | Show active deploy routes |

Observe:

| Command | What it does | | --- | --- | | hs-x status | Show project health | | hs-x logs | Stream runtime and deploy telemetry | | hs-x drift | Show project drift | | hs-x audit list | List redacted account audit rows | | hs-x history | Show recent command runs |

Account:

| Command | What it does | | --- | --- | | hs-x login | Authenticate with an HS-X account token | | hs-x accounts | Manage HS-X accounts | | hs-x whoami | Show the active HS-X account | | hs-x logout | Remove the active HS-X account | | hs-x link | Attach this project to your HS-X account | | hs-x unlink | Clear the session; keep local project state |

Config:

| Command | What it does | | --- | --- | | hs-x secrets | Store app secrets for runtime deploys | | hs-x completion <shell> | Generate shell completion (bash, zsh, fish) | | hs-x update | Check for a newer CLI release | | hs-x help | Show command help |

Run hs-x <command> --help for command-specific flags. Most commands accept --json for machine-readable output, and prompts can be skipped in scripts with --yes where a command confirms before changing anything.

Connecting accounts

hs-x connect walks HubSpot and Cloudflare setup back to back; each side is also available on its own.

hs-x connect hubspot      # HubSpot developer account: PAK, or discovered from `hs accounts auth`
hs-x connect cloudflare   # Cloudflare: browser OAuth flow, or --auth-method api-token

For HubSpot, the CLI discovers credentials from the official HubSpot CLI config when you have run hs accounts auth, or accepts a developer personal access key via --pak. For Cloudflare, an interactive run uses a browser authorization-code flow by default; --auth-method api-token accepts a scoped API token you create in the Cloudflare dashboard and paste back, which also suits CI and headless shells.

Migrating an existing app

hs-x migrate run takes a legacy HubSpot app (platform versions 2023.2, 2025.1, or 2025.2) and generates a 2026.03 HS-X project as a net-new duplicate you can test with hs-x dev. Your original app keeps running untouched until you cut over. See hs-x migrate --help for the inspect, report, cards, and swap-cards subcommands.

Docs

Guides and reference live at hs-x.dev/docs. The getting-started guide goes from an empty directory to a live HubSpot card in about fifteen minutes.

License

Apache-2.0