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.
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
- Choose your server.
- In the browser, select Authorize CLI Access.
- 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.
- Choose where to save the code.
The CLI creates the App and its development environment in BotDojo,
downloads the code, and installs its dependencies.
| Starter | What you get |
|---|---|
| Empty App | A blank starting point. |
| Purchase Requests | A sample for creating and approving requests. |
| Feature Lab | A 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:
- Open Apps in the project and select the App, or run
botdojo-app open. - Open Preview App and repeat the 300 approval.
- 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.)--seedloadsseed.jsoninto an empty, non-production environment.--env <name>deploys to another environment, and creates it if needed.--uploadbuilds 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.
| Command | What it does |
|---|---|
login | Signs in and connects a folder to an App. --no-open prints the sign-in link. |
init [dir] | Creates a starter without signing in. |
dev | Runs the App in the local preview. |
test | Runs the files in test/ against a local copy of the App. |
build | Builds into .botdojo/build and adds new IDs to botdojo.app.lock.json. Commit the lock file. |
deploy | Pushes, builds on BotDojo, shows the plan, and deploys. |
push | Commits 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. |
apps | Lists the project's Apps, or only this folder's App. |
open | Opens the App page. |
status | Shows the App's stable IDs and local data migrations. |
env set NAME=value | Sets env vars, including secrets, in an environment. |
env create <name>, store | Creates an environment and manages its Store. See Data Stores. |
doctor | Checks 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
| Symptom | Check |
|---|---|
node:sqlite is unavailable | Use Node.js 22.13 or later. |
TypeScript cannot find node:test | Run 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 denied | Ask an account administrator to check your membership. |
| A required env var is missing | Deploy with --vars-file, or use env set. .env.local alone affects local runs. |
| The build cannot start on BotDojo | Deploy with --upload, and tell your administrator. |
WORKFLOW_UNAVAILABLE locally | Workflows run on BotDojo only. Deploy to test them. |
| A connection call needs permission | See Connections the App uses. |