botdojo-tool

CLI for accessing BotDojo Agent Pack MCPs using a project Resource Token.

Installation

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

This installs the global botdojo-tool command.

What It Does

• Registers a Resource Token and stores local credentials.
• Calls BotDojo Agent Pack MCP tools through the MCP gateway.
• Refreshes access tokens automatically.
• Automatically re-runs registration when refresh requires re-approval.

Requirements

• Node.js 18+ (uses built-in fetch)
• A BotDojo Resource Token (bdres_...)
• BotDojo API URL via:
  • --api-url when running register, or
  • BOTDOJO_API_URL env var

Local Development

From repo root:

pnpm --filter ./packages/botdojo-tool-cli build
node packages/botdojo-tool-cli/lib/cli.js --help

From package directory:

pnpm build
node lib/cli.js --help

Global link for local development:

cd packages/botdojo-tool-cli
pnpm link --global
pnpm dev

Quick Start

1. Register once:

botdojo-tool register bdres_your_token_here --api-url https://api.botdojo.com

2. Inspect the Agent Pack MCP:

botdojo-tool tools
botdojo-tool agent_context
botdojo-tool list_resources
botdojo-tool search_for_resource "gmail" --limit 5

3. Use the exact agent-pack tool wrappers:

botdojo-tool read_resource "botdojo://project/tools/my-email/TOOLS.md" --expand
botdojo-tool call_tool "botdojo://project/tools/my-email/TOOLS.md" searchMessages '{"q":"from:[email protected]"}'

4. Call any MCP tool directly:

botdojo-tool e agent_context
botdojo-tool e skills_search '{"query":"postgres","limit":5}'

Cheat Sheet

# Build locally
pnpm --filter ./packages/botdojo-tool-cli build

# Show help
node packages/botdojo-tool-cli/lib/cli.js --help

# First-time setup
botdojo-tool register bdres_your_token_here --api-url https://api.botdojo.com

# List exposed MCP tools
botdojo-tool tools

# Agent Pack core tools
botdojo-tool agent_context
botdojo-tool list_resources
botdojo-tool list_resources --mime-type text/markdown
botdojo-tool list_resources --format json
botdojo-tool search_for_resource "gmail"
botdojo-tool search_for_resource "gmail" --limit 5
botdojo-tool search_for_resource "gmail" --mime-type text/markdown
botdojo-tool read_resource "botdojo://project/tools/my-email/TOOLS.md"
botdojo-tool read_resource "botdojo://project/tools/my-email/TOOLS.md" --metadata-only
botdojo-tool read_resource "botdojo://project/tools/my-email/TOOLS.md" --expand
botdojo-tool read_resource "botdojo://project/tools/my-email/TOOLS.md" --reason "Need tool schema before calling it"
botdojo-tool call_tool "botdojo://project/tools/my-email/TOOLS.md" searchMessages '{"q":"from:[email protected]"}'
botdojo-tool call_tool "botdojo://project/tools/my-email/TOOLS.md" searchMessages 'q=from:[email protected]'
botdojo-tool call_tool "agent://me/subagent/TOOLS.md" sub_agent_call '{"prompt":"Draft a release checklist"}'

# Optional agent-pack tools
botdojo-tool skills_search "postgres" --limit 5
botdojo-tool view_skill postgres_guide
botdojo-tool view_skill postgres_guide --collection "Shared Skills"
botdojo-tool skills_collection_repo
botdojo-tool skills_collection_repo "Shared Skills" --write --ttl-seconds 900

# Call any MCP tool directly
botdojo-tool e my_tool
botdojo-tool e my_tool '{"q":"hello","limit":3}'
botdojo-tool e my_tool 'q=hello,limit=3,enabled=true'

Command Reference

| Command | Purpose | Common options | | --- | --- | --- | | register <resource_token> | Exchange a bdres_... token for local credentials | --api-url <url> | | tools | List MCP tools exposed by the gateway | none | | e <tool_name> [parameters] | Call any MCP tool directly | JSON or key=value args | | agent_context | Load agent instructions, memory, skills guidance, and available resources | none | | list_resources | List resources exposed through the agent pack | --mime-type <type>, --format <text\|json> | | search_for_resource <query> | Search resources exposed through the agent pack | --limit <n>, --mime-type <type> | | read_resource <uri> | Read a resource | --metadata-only, --expand, --reason | | call_tool <mcp_uri> <tool_name> [parameters] | Call a tool inside a specific MCP URI | --reason <text> | | skills_search <query> | Search configured skills collections | --limit <n> | | view_skill <skill_id> | Load a skill's SKILL.md quick view | --collection <name> | | skills_collection_repo [collection] | Get temporary clone metadata for a skills collection | --write, --ttl-seconds <n> |

Parameters

e and call_tool accept either:

• JSON object: {"key":"value","limit":3}
• key=value pairs: key=value,limit=3,enabled=true

Basic coercions for key=value format:

• true / false -> booleans
• null -> null
• numbers like 5 or 3.14 -> numbers

Stored State

• Credentials file: ~/.bd_resource/credentials.json
• Reused automatically after register
• Includes access token, refresh token, and MCP session ID

Good To Know

• You only need --api-url during register; later commands reuse the stored API URL.
• Access tokens refresh automatically.
• If refresh requires re-approval, the CLI re-registers automatically and continues.
• If the saved MCP session is stale, the CLI reconnects and retries automatically.
• The wrapper commands intentionally mirror the Agent Pack MCP tool names.

Common Failure Messages

• API URL is required... Run botdojo-tool register ... --api-url <url> or set BOTDOJO_API_URL.
• No local registration found... Run botdojo-tool register <resource_token> first.
• Tool "<name>" was not found... Run botdojo-tool tools and verify that the target Agent Pack exposes that tool.

Publishing

From the repo root:

pnpm publish:tool-cli

From the package directory:

pnpm build
pnpm publish --access public

Commands

register <resource_token>                                     Register and store credentials
tools                                                         List available MCP tools
e <tool_name> [parameters]                                    Call a tool directly
agent_context                                                 Load agent instructions, memory, and available resources
list_resources                                                List resources
read_resource <uri>                                           Read resource content/metadata
search_for_resource <query>                                   Search resources
call_tool <mcp_uri> <tool_name> [parameters]                  Call tool inside an MCP URI
skills_collection_repo [collection]                           Get skills collection clone metadata
view_skill <skill_id>                                         View a skill quick reference
skills_search <query>                                         Search skills collections

After register, the CLI reuses the stored API URL from local credentials. You do not need to pass --api-url on other commands.

Credentials Storage

Credentials are stored at:

~/.bd_resource/credentials.json

The CLI writes this file with restrictive permissions (0600).

Notes

• If access tokens expire, the CLI refreshes automatically.
• If refresh fails due invalidation/re-approval requirements, the CLI re-registers and continues after approval.
• MCP session IDs are persisted to reduce repeated negotiation.

Troubleshooting

• API URL is required...
  • Pass --api-url on register (or set BOTDOJO_API_URL) and register again.
• No local registration found...
  • Run botdojo-tool register <resource_token> first.
• Tool "<name>" was not found...
  • Run botdojo-tool tools and verify the exposed tool names on the target server.