Octopus CLI

octopus-cli is the user CLI for BotWorks.

Update

octopus-cli checks for newer npm releases in the background and may include _notice.update in JSON output. Check or install the latest version:

octopus-cli update --check --json
octopus-cli update

The update command uses npm and verifies octopus-cli --version after install.

Login

octopus-cli auth login --web-url <tenant-web-origin>

The command creates an Account JCode authorization request for the tenant Portal origin supplied through --web-url and prints the URL plus authorization code. Approve it in Portal; the selected team and runtime context are saved with the profile. When --profile is omitted, credentials are saved to the default profile under ~/.config/syngy-octopus-cli.

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

octopus-cli auth login --web-url <tenant-web-origin> --no-open --no-wait
octopus-cli auth login --complete

In a non-interactive shell, login automatically uses the same two-step path as --no-wait; --web-url is still required when creating the pending login.

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:

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

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

Arcubase

octopus-cli arcubase and octopus-cli arcubase-admin run the published Arcubase CLI package through the current Octopus CLI profile and selected team.

octopus-cli arcubase entry
octopus-cli arcubase table get --app-id <app_id> --table-id <table_id>
octopus-cli arcubase row query --app-id <app_id> --table-id <table_id> --body-json '{"limit":20,"offset":0}'
octopus-cli arcubase-admin app list
octopus-cli arcubase-admin table get --app-id <app_id> --table-id <table_id>

Use --profile <name> to select a different Octopus login profile, and --team-id <teamId> to override the team saved in that profile.

octopus-cli --profile prerelease arcubase --team-id <teamId> entry

Skills Sync

List online skills from the selected team:

octopus-cli skills list
octopus-cli skills list --query <text> --json

Sync team skills into an OpenAI/Codex skill directory:

octopus-cli skills sync --mode openai --id <skillId>
octopus-cli skills sync --mode openai --name <skillName>
octopus-cli skills sync --mode openai --all
octopus-cli skills sync --mode openai --global --id <skillId>

Supported sync modes: openai.

Without --global, skills are written under ./.codex/skills/<skill-name>/ from the current working directory. With --global, skills are written under ~/.codex/skills/<skill-name>/.

Newly synced skills may require a new Codex session or agent restart before they are loaded.

Conversations

List recent conversations:

octopus-cli conversation list

By default this prints a compact text table with conversation id, title, assistant, last update, sequence, and last message. The default limit is 20; use --limit <n> when you need more or fewer rows. Use JSON for scripts:

octopus-cli conversation list --json
octopus-cli conversation list --limit 50 --json

Show one conversation's history:

octopus-cli conversation history <conversationId>

List digital employees that can start conversations:

octopus-cli digi-employee list
octopus-cli digi-employee list --query <text> --json

The list output is intentionally compact for conversation selection: digiEmployeeId, name, bio, avatar, skillsets, tools, and quickStartPrompts.

Remote Browser

remote-browser exposes cloud browser sessions for local agents. It prints JSON by default and only works with cloud browser instances.

octopus-cli remote-browser help
octopus-cli remote-browser list
octopus-cli remote-browser session create --browser-instance-id <browserInstanceId>
octopus-cli remote-browser navigate <runtimeSessionId> --url https://example.com
octopus-cli remote-browser snapshot <runtimeSessionId>
octopus-cli remote-browser act <runtimeSessionId> --action click --ref <ref>
octopus-cli remote-browser screenshot <runtimeSessionId> --output ./shot.png
octopus-cli remote-browser evaluate <runtimeSessionId> --script "return location.href"
octopus-cli remote-browser live-view <runtimeSessionId>
octopus-cli remote-browser handoff start <runtimeSessionId>
octopus-cli remote-browser handoff complete <runtimeSessionId> --handoff-id <handoffId>
octopus-cli remote-browser session delete <runtimeSessionId>

Start a new conversation and optionally attach the SSE stream:

octopus-cli conversation send \
  --digi-employee-id <digiEmployeeId> \
  --content "<prompt>" \
  --watch

Continue an existing conversation:

octopus-cli conversation send <conversationId> --content "<prompt>" --watch

Attach local files to the same human message:

octopus-cli conversation send <conversationId> \
  --content "<prompt>" \
  --file ./report.pdf \
  --file ./screenshot.png \
  --watch

Attach an existing conversation stream:

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

The stream commands print NDJSON events. They do not require manually passing user access tokens or stream tickets. When conversation send 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 '{}'
octopus-cli configure webskill publish . --publish-note "initial publish"

configure webskill publish reads package.json.name as the package identity and uploads the directory as a web skill package. package.json.name format is @scope/package; each segment is 1-100 chars using lowercase letters, numbers, ., _, or -.