BotDojo CLI

Command-line interface for BotDojo. Authenticate, manage flows, run tests, and more.

Installation

npm install -g @botdojo/cli
# or
pnpm add -g @botdojo/cli

Quick Start

# Setup the SDK playground (clone, install, and configure)
botdojo playground

# Login to BotDojo
botdojo login

# Check status
botdojo status

# Create or switch to a project
botdojo project create "My Project"

# Clone a flow
botdojo cloneToProject botdojo.com/account/project/flow-id

# Create a flow API key
botdojo flow api_key create <flow-id>

Commands

Getting Started

botdojo playground

Clone and setup the SDK playground repository. This command:

• Clones the sdk-playground repo from GitHub
• Installs all dependencies
• Runs the setup script to configure your environment

botdojo playground

After setup completes:

cd sdk-playground
npm run dev
# Open http://localhost:3500

Authentication

botdojo login

Authenticate with BotDojo. Opens browser for OAuth authentication.

Options:

• --force-select - Force account/project selection even if already configured
• --api-key <key> - Authenticate with API key
• --account-id <id> - Account ID (required with --api-key)
• --project-id <id> - Project ID (required with --api-key)

botdojo logout

Remove authentication credentials.

botdojo reauth

Refresh your authentication token.

botdojo status

Show current authentication and project status.

botdojo switch

Switch to a different account or project.

Options:

• --account-id <accountId> - Account ID to switch to (non-interactive mode)
• --project-id <projectId> - Project ID to switch to (non-interactive mode)

Examples:

# Interactive mode - prompts for account and project selection
botdojo switch

# Non-interactive mode - switch directly to specific account/project
botdojo switch --account-id abc-123 --project-id def-456

Note: When using --account-id and --project-id, both must be provided together for non-interactive mode.

Project Management

botdojo project create <name>

Create or switch to a project. If the project already exists, it will ask if you want to use it.

Options:

• -y, --yes - Skip confirmation prompts (auto-accept)
• --force - Force operation without prompts

Examples:

# Create/select with prompts
botdojo project create "SDK Playground"

# Auto-create/select without prompts
botdojo project create "SDK Playground" --yes

# Force create/select
botdojo project create "SDK Playground" --force

Flow Management

botdojo cloneToProject <uri>

Clone a flow from a URI to your current project.

Options:

• -n, --name <name> - Custom name for the cloned flow
• -f, --folder <folder> - Folder path to clone the flow into

Example:

botdojo cloneToProject botdojo.com/botdojo/sdk-test-flows/flow-id --name "My Test Flow"

botdojo clone <flow-id>

Clone a flow by ID to a local folder with config files.

botdojo flow list

List all flows with their details.

botdojo flow get <flow-id>

Get full flow details by flow ID.

Options:

• -v, --version <version> - Specific version to retrieve

Flow API Keys

botdojo flow api_key create <flow-id>

Create a new API key for a specific flow.

Options:

• -n, --name <name> - Custom name for the API key

Example:

botdojo flow api_key create abc-123 --name "Production Key"

Note: These are flow API keys scoped to a single flow only. They're safe to use in client-side applications.

botdojo flow api_key list

List all flow API keys.

Options:

• -f, --flow-id <flow-id> - Filter by specific flow ID
• -i, --id <id> - Get a specific API key by ID

botdojo flow api_key archive <key-id>

Archive (delete) a flow API key.

Options:

• --force - Skip confirmation prompt

Local Development

botdojo run [folder]

Run a flow from a local folder configuration.

Options:

• -i, --input <text> - Input text for the flow

botdojo pull [folder]

Update local YAML files with latest flow configuration from server.

botdojo pull-from-origin <flow-id>

Pull the latest release from the original flow source (where it was cloned from). This updates your local flow with the latest version from its origin.

Options:

• -y, --yes - Skip confirmation prompts
• -v, --version <version> - Specific version to pull (default: latest)

Examples:

# Pull latest release from origin
botdojo pull-from-origin abc-123

# Pull specific version
botdojo pull-from-origin abc-123 --version 1.2.0

# Auto-confirm without prompts
botdojo pull-from-origin abc-123 --yes

Note: Only flows that were cloned from another source can use this command.

botdojo checkout <branch>

Switch to a branch (creates if it doesn't exist).

Options:

• --force - Create new branch without prompting

botdojo branch <action>

Manage branches (actions: list).

botdojo publish

Publish local changes to the current branch.

Options:

• -m, --message <message> - Publish message/description
• --force - Force publish even if version conflicts

botdojo diff [branch]

Show differences between local changes and published branch.

Options:

• -f, --folder <folder> - Flow folder to compare

Flow Requests

botdojo flow_request get <flow-request-id>

Get full flow request details by flow request ID.

botdojo flow_request get_trace <flow-request-id>

Get full trace for a flow request by flow request ID.

Development

botdojo repl

Start interactive mode for debugging and testing commands.

Configuration

The CLI stores configuration in:

• ~/.botdojo/credentials.json - Authentication tokens
• ~/.botdojo/config.json - Account ID, project ID, API URL

Environment Variables

The CLI connects to production BotDojo servers by default. You can override these with environment variables if needed:

• BOTDOJO_APP_URL - BotDojo web app URL (default: https://app.botdojo.com)
• BOTDOJO_API_URL - API server URL (default: https://api.botdojo.com/api/v1)
• BOTDOJO_SOCKETIO_SERVER_URL - Socket.IO server URL (default: https://api.botdojo.com)

Development

See AGENTS.md for development documentation.

License

MIT