CLI

Run Octo from your terminal

Everything the dashboard does — agents, workflows, phone numbers, billing — as one scriptable binary. Built for terminals, CI pipelines, and agent runtimes that would rather call a command than click a button.

$ npm install -g @appbox/oneocto-cli

Requires Node 20+. Check the install with oneocto -v.

Browse the commands Full documentation View on npm
oneocto 
$ oneocto auth login --url https://acme.oneocto.dev✔ Signed in as ops@acme.com — tenant acme (dev)$ oneocto list entry-points --tabularID        NAME              PHONE NUMBER    STATUSep_8f21   Support inbound   +1 415 555 0142  activeep_4c09   Renewals outbound +1 415 555 0188  active$ oneocto flow simulate wf_2b7d -m "I need to reschedule"{  "verdict": "pass",  "matchedNode": "intent.reschedule",  "latencyMs": 812}

Quick start

Three commands to your first call

1

Install it

Node 20 or newer. The package installs a single oneocto binary.

npm install -g @appbox/oneocto-cli
2

Sign in

Paste your workspace URL and the CLI reads the tenant and environment from it.

oneocto auth login --url https://acme.oneocto.dev
3

Ask it what it can do

The command surface is generated from a registry, so the CLI is its own reference.

oneocto resources

Self-describing

The CLI is its own documentation

Commands are generated from a resource registry rather than hand-written one by one. Ask the binary what exists and it answers with the current contract — no stale reference page to drift out of sync, which is what makes it safe to hand to an AI agent.

  • ✓resources lists everything the CLI can touch, with aliases
  • ✓describe returns the operational contract for a resource
  • ✓explain adds build guidance for the complicated ones
  • ✓JSON out by default — --tabular when a human is reading

Resources today

contactstoolsllm-settingsworkflowsworkflow-nodesworkflow-versionsentry-pointsinteractionsusersrolesuser-roles

Each one supports the same verbs, so learning one resource teaches you the rest. Run oneocto resources for the live list.

Reference

Command surface

One verb, one resource, one shape. Anything that hits the API takes --tenant and --space-id to override the saved context.

Auth & tenants

oneocto auth login --url <url>
Sign in; also takes --tenant, --email, --env dev|prod
oneocto auth whoami
Show who the saved credentials resolve to
oneocto auth logout
Drop the saved login
oneocto tenant list
List every tenant you have signed into
oneocto tenant use <slug>
Switch the default tenant — interactive in a TTY
oneocto tenant remove <slug> --yes
Forget a tenant

Discovery

oneocto about
What the CLI is and how it is organized
oneocto resources
Every resource, its aliases, and the verbs it supports
oneocto describe <resource>
The operational contract for one resource
oneocto explain <resource>
Deeper build guidance, plus any linked docs
oneocto authoring [topic]
Authoring guidance for building things well

Resources

oneocto list <resource>
List records
oneocto get <resource> <id>
Fetch one record
oneocto create <resource> --data '{...}'
Create from inline JSON
oneocto update <resource> <id> --data '{...}'
Patch a record
oneocto delete <resource> <id> --yes
Delete, with confirmation skipped for automation
oneocto publish <resource> <id>
Publish a draft; start-draft goes the other way
oneocto storage bulk create <resource>
Bulk create, update, delete, and associate

Workflows

oneocto flow list
Available code-defined flows
oneocto flow scaffold <flow>
Emit a valid starting spec, ready to edit
oneocto flow publish-workflow --spec <file>
Create a workflow and a published version from one spec
oneocto flow revise-workflow <id> --spec <file>
Apply an edited spec, starting a draft when needed
oneocto flow simulate <workflow-id> -m "..."
Run a workflow with one message, get a verdict
oneocto flow diagnose <execution-log-id>
Failing node, resolved input, unresolved references
oneocto flow audit <workflow-version-id>
Pre-publish readiness report
oneocto flow export <workflow-id>
Write an existing workflow back out as a spec

Calls & numbers

oneocto execute interaction <id> -m "..."
Send a message to an existing interaction
oneocto telephony search-numbers
Find numbers you can buy
oneocto telephony purchase-number
Provision a number; release-number gives it back
oneocto telephony recording-url <id>
Signed URL for a call recording
oneocto telephony twilio-setup
Wire up Twilio; twilio-teardown unwires it
oneocto schedules create
Create, update, and inspect runs for scheduled work

Billing

oneocto billing select-plan <plan-id>
Move the workspace onto a plan
oneocto billing top-up
Buy credits outside the auto top-up
oneocto billing add-card
Add, confirm, default, and remove payment methods

Automation

Ship workflows from your pipeline

Keep workflow specs in git, validate them on every pull request, and publish on merge. --dry-run tells you what would change without writing anything, and every command exits non-zero when it fails, so CI catches it.

  • ✓Non-interactive: pass slugs and --yes instead of answering prompts
  • ✓flow audit as a pre-publish gate
  • ✓--minified JSON pipes straight into jq
.github/workflows/publish-agent.yml 
steps:
  - uses: actions/checkout@v4
  - run: npm install -g @appbox/oneocto-cli

  - name: Sign in
    run: >
      oneocto auth login
      --tenant acme
      --email ${{ secrets.OCTO_EMAIL }}
      --password ${{ secrets.OCTO_PASSWORD }}

  - name: Validate the spec
    run: oneocto flow publish-workflow --spec ./agents/support.json --dry-run

  - name: Publish on merge
    if: github.ref == 'refs/heads/main'
    run: oneocto flow publish-workflow --spec ./agents/support.json

Prefer the terminal?

Install the CLI and have an agent answering calls before your coffee lands.

Read the docs Talk to Sales