@backstep/cli

bs, the command line for backstep. Every command runs on your live project.

npx @backstep/cli pull c0ffee   # set up ./c0ffee; asks for the project's secret once
cd c0ffee
npx bs stub Reef.Snorkeler.fullName
npx bs run Reef.Snorkeler.fullName

Run bs help for every command. It needs Node 22 or later.

bs is an MCP client of your project's server at https://backstep.dev/<id>/bs/mcp: besides pull and stub, its commands are that server's tools, e.g. bs relink for Index__Index__relink. Any MCP client can connect to the same URL, with the secret as a bearer token or through OAuth.

No folder? Name the project and secret instead, from anywhere: BACKSTEP_PROJECT=<id> BACKSTEP_SECRET=<secret> npx @backstep/cli refs, or --project and --secret. Everything works that way except bs stub, which writes a file.

<projectId>/
  project.json        the project's id, and its server if not backstep.dev
  .secret             its secret; keep it out of git (bs pull writes a .gitignore)
  project/            a folder per package, starting with the project's own
    .backstep/        snapshots of the live index and types: don't edit
    snorkeler/fullName.ts   your code, one file per code slot

• Packages: bs change Billing create adds a billing/ folder.
• Snapshots: never edit a .backstep folder; change the index with bs change.
• The server is https://backstep.dev. --url or BACKSTEP_URL points elsewhere, and BACKSTEP_SECRET can hold the secret instead of .secret.