Getting started

Follow J1: connect an existing repository, qualify a revision, deploy to staging, and open its Surface. You need Node 22+, access to a BellD workspace, and an application that meets the hosted-app descriptor and evaluation requirements. Replace every example ID with the ID returned by your environment.

Install and sign in

From a BellD repository checkout, build the CLI. Define the shell helper below so belld works when you change into your application directory. If the CLI bin is already installed, the helper is unnecessary.

pnpm install
pnpm --filter @belld/cli build
export BELLD_CLI="$(pwd)/cli/dist/bin.js"
belld() { node "$BELLD_CLI" "$@"; }
node cli/dist/bin.js login --api-url https://api.staging.belld.ai --issuer https://auth.staging.belld.ai/realms/belld --client-id belld-cli
node cli/dist/bin.js workspace list
node cli/dist/bin.js workspace use ws_REPLACE

Use the staging API URL for subsequent commands (or pass --api-url each time). Run project commands from your application's repository directory.

export BELLD_API_URL=https://api.staging.belld.ai
belld init --repo https://github.com/OWNER/APP.git --ref main --json

For an existing BellD Product, use belld link prod_REPLACE instead of init. Both paths write the local project mapping. The mapping contains workspace and Product IDs, never a credential. Keep the Product ID returned by init or link.

Inspect and confirm the revision

belld status --json
belld doctor
belld revision list --product prod_REPLACE --json
belld revision get rev_REPLACE --json
belld revision confirm rev_REPLACE --product prod_REPLACE --json
belld capability inspect rev_REPLACE --json
belld binding status --product prod_REPLACE --revision rev_REPLACE --json

Select the revision created by this intake. Confirm only after reviewing its detected descriptor. Required workspace-owned capabilities need appropriate credentials and provider bindings. See the capability catalog and credential command. Supply secrets through stdin or --from-env NAME. Platform-owned capabilities follow their own catalog requirements.

Evaluate qualification

belld evaluate rev_REPLACE --intent qualification --json
belld pipeline-run get pipe_REPLACE --json

Evaluation polls within its timeout. Continue only when the response has qualification.status equal to qualified. A successful HTTP response or exit 0 alone does not mean qualification passed. Inspect findings and use belld explain rev_REPLACE when it stops. Correct the application, create a new intake/revision, and evaluate again.

Release and deploy

belld release create --product prod_REPLACE --revision rev_REPLACE --json
belld deploy rel_REPLACE --environment staging --json
belld deployment get dep_REPLACE --json

Use the returned release and deployment IDs. Creating a release from a revision requires exactly one version; use --version instead of --revision if needed. Recheck deployment with a bounded deadline until it reaches its terminal state. Deployment GET reads once; it does not poll. If deployment fails, inspect its status/reason and belld explain dep_REPLACE before retrying.

Access the application

belld surface get srf_REPLACE --json

Take surface_id from the deployment result and open the URL returned by the active Surface in a browser. Complete the access/sign-in flow required by the release audience; a published URL does not bypass access policy. Do not invent a hostname from resource IDs. This CLI has no access command.

See CLI behavior for polling and exit codes, Control API for resource responses, and J1 for the source coverage snapshot. The staging walkthrough is verified separately by the owner.