@beylogic/chipote

The Chipote CLI is the developer toolchain for authoring, validating, registering, deploying and installing apps on the BeyLogic platform. It turns a local app manifest into an immutable release and manages partner-scoped installations — the same public workflow partners use to ship and consume apps.

Install

npm install -g @beylogic/chipote
# or run on demand without installing:
npx @beylogic/chipote <command>
# with bun:
bunx @beylogic/chipote <command>

Quick start

# Scaffold a new app (YAML-first, no fake build placeholders)
chipote init my-app --slug acme/my-app --display-name "My App" --author "Acme"

# Validate locally (no credentials, no network)
chipote validate ./my-app

# Record ownership for a partner
chipote register ./my-app --owner <ownerPartnerId>

# Deterministic bundle → per-artifact upload → immutable release
chipote deploy ./my-app --stage development --channel stable --version 1.0.0

# Install into a partner site (release-aware)
chipote install --site acme.beylogic.link --app acme/my-app \
  --stage development --channel stable --scope partner

Configuration

| Commands | Public configuration | |---|---| | register, deploy, list | BL_ADMIN_API_URL + BL_ADMIN_TOKEN | | install, upgrade, remove | BL_SITE_TOKEN plus --site <host-or-url> or BL_SITE | | init, validate | No credentials or network |

Admin credentials can alternatively live in ~/.config/beylogic/app-deploy.json as apiUrl and token (environment values take precedence). Interactive login/SSO is not yet implemented.

BL_ADMIN_API_URL is an HTTP(S) origin such as https://admin.beylogic.com with no /api path; the CLI appends /api/v1/... itself. Release submission returns a relative statusUrl that the CLI resolves against the configured origin. Artifact bytes upload directly to presigned URLs without the admin Authorization header. Tokens and presigned URLs are never printed.

Targeting a non-default environment

The CLI is URL-first: there is no --env/--environment flag and --stage is NOT an endpoint selector — it is only the release dimension (development/production) threaded into release/upgrade/status bodies. You point the CLI at a deployment by pointing its URL variables at that deployment's origins:

# Admin surface (register/deploy/list) — the root admin API of the deployment
export BL_ADMIN_API_URL="https://<admin-api-origin>"   # bare origin, no /api path
export BL_ADMIN_TOKEN="<admin token>"

# Site surface (install/upgrade/remove) — the partner portal origin that fronts
# bl_api (Host-header partner resolution), e.g. the CloudFront domain of the
# partner stack. No --site flag needed while BL_SITE is exported.
export BL_SITE="https://<partner-portal-origin>"
export BL_SITE_TOKEN="<site token>"

chipote install --app acme/inventory --stage development --scope partner

With these exported, every verb targets that deployment; an explicit --site <host-or-url> on install/upgrade/remove overrides BL_SITE for one invocation. Precedence is flag > env > (admin only) ~/.config/beylogic/ config file.

Lifecycle

# Record ownership (writes the returned app id into the manifest)
chipote register ./my-app --owner <ownerPartnerId>

# Deterministic bundle, per-artifact upload, immutable release submission
chipote deploy ./my-app --stage development --release-channel beta \
  --version 1.2.0 --idempotency-key <uuid> --build

chipote list --stage development

# Install the latest active release; all declared scopes are granted when omitted
chipote install --site acme.beylogic.link --app acme/my-app \
  --stage development --channel stable --scope partner

# Pin a release and reduce consent (--grant-scope is repeatable)
chipote install --site acme.beylogic.link --app acme/my-app \
  --stage development --channel beta --version 1.2.0 \
  --scope workspace --workspace <workspaceId> \
  --grant-scope cmdb:read --grant-scope agents:invoke \
  --idempotency-key <uuid>

# Upgrade to latest, or pin with --to; omitted grants never silently widen
chipote upgrade --site acme.beylogic.link --app acme/my-app \
  --stage development --channel beta --to 1.3.0 \
  --scope workspace --workspace <workspaceId>

# Disable an installation (release/runtime history is retained)
chipote remove --site acme.beylogic.link --app acme/my-app \
  --stage development --scope workspace --workspace <workspaceId>

Use --scope client --client <clientId> for client scope. Partner operations default to stage=production, scope=partner, and server-side channel=stable. --revoke-all-scopes cannot be combined with --grant-scope.

Install/upgrade/remove are operation-driven: each sends an idempotencyKey (--idempotency-key when supplied, otherwise a fresh random UUID) and prints operationId, operationStatus, and statusUrl. Re-running with the same key replays the recorded operation; a key reused for a different action/release/ scope fails with 409.

Release immutability

The server recomputes the canonical manifest SHA-256. Re-publishing the same app identity/version/channel returns the original operation only when the manifest and every artifact checksum match; drift is 409. Reusing one idempotency key for another release is also 409. Change the manifest version for changed content.

deploy prints the app identity, stage/channel, canonical manifest SHA prefix, each artifact's kind/SHA prefix/byte count, then releaseId, operationId, and statusUrl. The CLI submits but does not poll or activate — operators poll the operation endpoint until a terminal status (active, failed, quarantined).

App manifests

An app manifest never supplies cloud accounts, VPCs, IAM, or platform credentials. It declares portable modules, artifacts, permissions, and settings only — validated and canonicalized against @beylogic/chipote-sdk.

Package development

bun test
bun run check
bun run build
npm publish --access public

The package depends only on the public @beylogic/chipote-sdk and yaml.

License

MIT. The source repository is hosted on GitHub (private).