Quickstart
Your first deploy with the forge CLI
The forge CLI deploys an app described by a blueforge.config.json in your repo and talks to the BlueForge control plane over HTTPS. Every command below is in forge --help.
1. Install the CLI
The CLI is the @blueforge-studio/forge package. The @blueforge-studio scope is published to BlueForge's own registry (packr), not npmjs.org, so point the scope at it once and then install globally:
npm config set @blueforge-studio:registry https://api.packr.blueforge.studio
npm install -g @blueforge-studio/forge
# or: pnpm add -g @blueforge-studio/forge
forge --help.npmrc form and the registry token.2. Log in
forge login authenticates and stores your credentials locally. Pass an API key with --api-key, or set FORGE_API_KEY in the environment (useful in CI).
forge login --api-key "$FORGE_API_KEY"3. Create or pick an organization
Organizations are the tenants everything else belongs to.
forge org create my-org
forge org list
forge org use my-org
forge org current4. Describe the app
From your repo root, forge init writes a blueforge.config.json. It detects the app type from package.json; override with the flags below. --force overwrites an existing file.
forge init --type next --port 3100 --domain my-app.example.com| Flag | Meaning |
|---|---|
--type | App type: next, vite, express, hono, java, dotnet (default: detected) |
--port | The port the app listens on (default 3100) |
--domain | Primary domain |
--force | Overwrite an existing blueforge.config.json |
forge sync registers the config with the control plane; run it after editing the file.
5. Deploy
forge app-deploy deploys the app in blueforge.config.json. --wait blocks until the deploy finishes, so a CI step fails when the deploy does.
forge app-deploy --waitUseful flags from the CLI's help:
| Flag | Meaning |
|---|---|
--wait | Wait for the deploy to finish |
--verify | Run the post-deploy smoke test against the deployed URL |
--preview | Deploy a preview |
--server | Submit the repo to the server-side build pipeline |
--from-git | Build the pushed forge-git tip instead of uploading the working tree |
6. Check status and logs
forge app status my-app
forge app status my-app --watch 5
forge app list
forge logs my-app --followforge app rollback my-app rolls back to the previous successful deploy.
7. API keys for CI
forge api-key create mints a key for a control-plane project. The plaintext is printed once; --out writes it to a 0600 file instead of the terminal.
forge api-key create --project my-app --name ci --out ./forge-ci.keyforge CLI in your pipeline. Registering deployments with the catalog from your own CI uses a different credential — an org API key from forge-auth. See API authentication.8. Show up in the catalog
Add the two sidecar files to your repo (blueforge.product.yml and blueforge.features.yml). On a platform deploy, forge-control registers the deployment with the catalog and uploads the imagery the sidecar declares. To register an app by hand:
forge blueforge-register my-app --url https://my-app.example.com --commit "$(git rev-parse HEAD)"Next: write the sidecars.