CLI
The Octo CLI (
oneocto) is a registry-driven command-line interface for discovering, inspecting, and managing Octo resources from a terminal or an agent runtime.
Everything the CLI returns is JSON, and the CLI describes its own capabilities. That makes one interface serve two readers: a person working at a prompt, and an AI agent deciding what to do next.
Key concepts
Section titled “Key concepts”| Term | Definition |
|---|---|
| Resource | A record type the CLI can operate on, such as workflows, tools, or interactions. |
| Verb | The action applied to a resource: list, get, create, update, delete. |
| Registry | The CLI’s internal catalog of resources, their verbs, aliases, and examples. It is the source of truth for what the CLI supports. |
| Tenant | A saved login pointing at one Octo deployment. The CLI can hold several and default to one. |
| Space | The scope most resources live in. Save a default space so you can stop passing --space-id. |
| Flow | A code-defined procedure that owns both the ordering and the mechanical details of a multi-step operation. |
What you can do
Section titled “What you can do”| Action | Description |
|---|---|
| Discover | Ask the CLI what resources exist, what verbs they support, and how to build them. |
| Read and write | Run the canonical CRUD verbs against any supported resource. |
| Run flows | Publish, revise, export, audit, and diagnose workflows through code-defined flows. |
| Execute | Run workflows, interactions, agents, prompts, and individual tools directly. |
| Operate | Manage schedules, telephony provisioning, billing, and system health. |
Quick start
Section titled “Quick start”- Install the CLI with
npm install -g @appbox.ai/oneocto-cli(Node 22 or newer). - Sign in with
oneocto auth login --url https://your-tenant.oneocto.com. - Pick a default space with
oneocto list spaces, thenoneocto tenant use. - Confirm the session with
oneocto auth whoami. - Ask the CLI what it supports with
oneocto resources.
oneocto list workflows --tabularDiscover before you act
Section titled “Discover before you act”The CLI is the source of truth for what it supports, so there is no need to guess a resource name, a verb, or a field:
oneocto about # what this is and how it is organizedoneocto resources # every resource, its aliases and supported verbsoneocto describe <resource> # the operational contract: verbs, fields, examplesoneocto explain <resource> # deeper guidance, pitfalls, related resourcesdescribe answers whether a resource is space-scoped and which verbs it accepts. explain covers how to think about the resource and links to longer-form guidance.
Do I need an API key to use the CLI?
No. The CLI authenticates as a user through oneocto auth login and stores credentials in your OS keychain. API keys are for external systems calling the platform directly.
Is the CLI a replacement for the console? No. It covers the same resources but suits automation, scripting, and agent runtimes. Visual work such as arranging a workflow canvas still belongs in the Workflow Builder.
Why does every command print JSON?
So output stays parseable by scripts and agents. Use --tabular when you want to read a list at a glance.
Related pages
Section titled “Related pages”- Installation - install, upgrade, and verify the CLI
- Authentication - sign in, manage tenants, and set a default space
- Command Reference - global options, verbs, queries, and command groups
- Resources - the resource model and what the CLI can operate on
- Flows - code-defined procedures for publishing and debugging workflows
- Using the CLI from an Agent - discovery order and safe automation patterns