Browse Apps
Apps · Build

botdojo-app CLI

Install the botdojo-app command, create and run an App on your computer, deploy it to a project, and look up each command.

4 min read

Install the CLI

You need Node.js 22.13 or later and npm.

npm install -g https://docs.botdojo.com/downloads/botdojo-app-cli-latest.tgz

Create your App

You need project administrator access. Start in the folder where you want the code.

botdojo-app login
  1. Choose your server.
  2. In the browser, select Authorize CLI Access.
  3. Back in the terminal, select the account and project, then Create a new App and a starter. To work on an App that already exists, select it instead.
  4. Choose where to save the code.

The CLI creates the App and its development environment in BotDojo, downloads the code, and installs its dependencies.

StarterWhat you get
Empty AppA blank starting point.
Purchase RequestsA sample for creating and approving requests.
Feature LabA Checks page that tries each SDK feature.

Run it on your computer:

cd purchase-requests
npm test
npm run dev

The local preview opens at http://localhost:4610. As Project admin, create a request for 300 and select Approve. The request becomes approved.

botdojo.app.json sets the server, App, and environment for commands run in that folder. If access expires, run botdojo-app login again in the folder.

Try a starter without signing in

botdojo-app init purchase-requests --template purchase-requests --install

Deploy

botdojo-app deploy --vars-file .env.local --seed

deploy pushes the folder to the App's repo, builds that commit on BotDojo, shows the plan (table changes, role changes, and blockers), asks you to confirm, and deploys. Then check it in BotDojo:

  1. Open Apps in the project and select the App, or run botdojo-app open.
  2. Open Preview App and repeat the 300 approval.
  3. To let someone else use it, select Share, then give a group the App in Account → Groups. See Roles, Sharing, and Access.

The options you need first:

  • --vars-file <file> saves the env vars the App requires. A deploy is blocked until each has a value. (Not --env-file, which Node.js reads itself.)
  • --seed loads seed.json into an empty, non-production environment.
  • --env <name> deploys to another environment, and creates it if needed.
  • --upload builds on your computer instead of on BotDojo.

In scripts and CI, outside a connected folder, set BOTDOJO_API_KEY, BOTDOJO_ACCOUNT_ID, and BOTDOJO_PROJECT_ID. The first deploy creates the App and its environment. For a server other than BotDojo, also set BOTDOJO_API_URL.

Deploy to production from the merged commit on the App's default branch, and avoid --yes there.

Command reference

Every command takes --help.

CommandWhat it does
loginSigns in and connects a folder to an App. --no-open prints the sign-in link.
init [dir]Creates a starter without signing in.
devRuns the App in the local preview.
testRuns the files in test/ against a local copy of the App.
buildBuilds into .botdojo/build and adds new IDs to botdojo.app.lock.json. Commit the lock file.
deployPushes, builds on BotDojo, shows the plan, and deploys.
pushCommits the folder to the App's repo. Never pushes .env files (except .env.example and .env.test), .botdojo/, or node_modules/.
pull <app> [dir]Downloads an App's source by name, ID, or source key. Stops if the folder has unpushed changes, unless you add --force.
appsLists the project's Apps, or only this folder's App.
openOpens the App page.
statusShows the App's stable IDs and local data migrations.
env set NAME=valueSets env vars, including secrets, in an environment.
env create <name>, storeCreates an environment and manages its Store. See Data Stores.
doctorChecks Node, dependencies, the App definition, and local variables. --remote checks project access.
docs [topic]Prints these guides. docs skill prints the App builder skill.

Run locally

dev opens the local preview at http://localhost:4610. It keeps local data in .botdojo/local.sqlite, loaded from seed.json, reads env vars from .env.local, and answers connection calls from fixtures/connections.json.

  • View as switches the caller between project administrator and any combination of roles.
  • Reset data reloads seed.json.

Troubleshooting

SymptomCheck
node:sqlite is unavailableUse Node.js 22.13 or later.
TypeScript cannot find node:testRun npm install.
PERMISSION_DENIED or "Not signed in"Run the command in the App folder, or run botdojo-app login again.
The account shows Access deniedAsk an account administrator to check your membership.
A required env var is missingDeploy with --vars-file, or use env set. .env.local alone affects local runs.
The build cannot start on BotDojoDeploy with --upload, and tell your administrator.
WORKFLOW_UNAVAILABLE locallyWorkflows run on BotDojo only. Deploy to test them.
A connection call needs permissionSee Connections the App uses.

Next steps