BotWorks CLI

botworks-cli is the user CLI for BotWorks.

Login

botworks-cli auth login --web-url https://www.example.com

The command creates a Web Auth Handoff and prints a browser pairing URL plus an 8 digit pairing code. When --profile is omitted, credentials are saved to the default profile under ~/.botworks-cli.

Use --no-open to print the URL without opening a browser. Use --no-wait when the browser pairing will be completed later:

botworks-cli auth login --web-url https://www.example.com --no-open --no-wait
botworks-cli auth login --complete

In a non-interactive shell, login automatically uses the same two-step path as --no-wait.

Profiles

Each profile is bound to one current team. Team-scoped commands read teamId from the active profile and do not accept a team id argument. Select the team after login:

botworks-cli auth profiles list
botworks-cli auth profiles use prod
botworks-cli team use <teamId>
botworks-cli --profile prod auth whoami

auth whoami --json prints the current profile, login identity, and selected team. If no team is selected, run botworks-cli team use <teamId> before using team-scoped commands.

Conversation Harness

Start a real conversation and attach the SSE stream:

botworks-cli conversation start \
  --digi-employee-id <digiEmployeeId> \
  --content "<prompt>" \
  --watch

Attach an existing conversation stream:

botworks-cli conversation watch <conversationId> --after-seq <seq>

The stream commands print NDJSON events and use a conversation stream ticket. They do not require manually passing user access tokens. When conversation start is run without --watch, it prints a conversation.watch_hint NDJSON line with the exact conversation watch command to attach later.

WebSkill Publish

Create and test a package locally, then publish it to the selected team:

npm create @syngy/webskill ./web-skills/example -- --title "Example workflow" --domain example.com
cd ./web-skills/example
npm install
npm run check
npm run run -- --url https://example.com --tool check_current_page --args '{}'
botworks-cli webskill publish .

webskill publish reads package.json.name as the package identity and uploads the directory as a web skill package.