Using the CLI from an Agent

The Octo CLI describes its own capabilities in machine-readable JSON, so an agent with permission to run local commands can discover what is possible instead of guessing.

This page is for an AI agent or copilot driving the CLI. It assumes the CLI is installed and a tenant is signed in.

Discovery order

Work down this list. Each step narrows the next.

1. oneocto about — what the CLI is for and how it is organized.
2. oneocto resources — the supported resource names, aliases, and verbs.
3. oneocto describe <resource> — the machine-readable contract for one resource.
4. oneocto explain <resource> — deeper guidance plus links to longer-form docs.

oneocto about
oneocto resources
oneocto describe entry-points
oneocto explain entry-points

Rules for automated callers

Rule	Why
Prefer canonical CLI resource names over backend table names.	Canonical names are stable; model names are internal.
Use aliases only when translating from an internal model name.	Aliases exist for translation, not as a second vocabulary.
Never guess whether a resource is space-scoped — read describe.	Guessing wrong silently targets the wrong scope.
Never guess supported verbs — read describe.	An unsupported verb fails late, after you have built the payload.
Inspect linked docs before constructing a payload for a complex resource.	Workflow versions and tools have rules a schema summary does not carry.
Use --output minified when the calling runtime parses the output.	Compact JSON is cheaper to pass around than the colored default.
Prefer a flow over hand-sequencing commands.	Flows own the mechanical fields, so they cannot be got wrong.

Before building a payload, read a working example rather than inventing field shapes:

oneocto list tools
oneocto get tools <id>
oneocto list workflow-nodes
oneocto get workflow-nodes <type>

Built-in authoring guidance

Workflow authoring has several non-obvious rules. The CLI ships them as data, available offline:

oneocto authoring              # the consolidated guide
oneocto authoring templates    # ${...} reference scoping per layer
oneocto authoring conditionals # deterministic vs LLM branching
oneocto authoring validate     # pre-publish checklist
oneocto authoring debug        # what to check when a run misbehaves

Read these before constructing a workflow version. They are the same rules the platform validates against.

Building a workflow step by step

Prefer oneocto flow publish-workflow when a single spec can describe the result — see Flows. Build the pieces individually only when you need control the flow does not expose.

1. Inspect what already exists

oneocto list workflows
oneocto list tools
oneocto list workflow-nodes

2. Create tools first

Tools are reusable capabilities the agent calls at runtime. Create them before the workflow version so their ids can be referenced.

There are two tool types:

• rest_api — calls an external HTTP endpoint. Use ${fields.<name>} to interpolate AI-extracted parameters.
• script — runs inline JavaScript, with the fields object in scope.

Define aiFields so the AI knows what to extract from the conversation. In advancedConfiguration, message types must be silent, static, or ai_generated.

3. Create the parent workflow

The parent record is a lightweight identity container. The executable graph lives on workflow-versions.

oneocto create workflows --data '{"name":"My Workflow","description":"What this workflow does"}'

4. Create the workflow version

This is the executable graph. It requires:

• sourceId pointing at the parent workflow
• llmProviderId set to a valid provider, found with oneocto list llm-settings
• llmSettings as an object such as {"temperature": 0, "maxTokens": 2000}, never null
• defaultLanguage, for example "en"
• definition.nodes and definition.edges describing the graph
• layout.nodes and layout.edges using the same ids as definition

For a large payload, write it to a file and compact it:

oneocto create workflow-versions --data "$(jq -c . my-version.json)"

5. Iterate

Updates replace rather than patch. Send the full definition and layout on every update, and always include sourceId, llmProviderId, defaultLanguage, and llmSettings — the backend validates them on every write.

oneocto update workflow-versions <version-id> --data "$(jq -c . my-version.json)"

6. Publish

oneocto publish workflow-versions <version-id> --change-description 'Initial release'

7. Route traffic to it

oneocto create entry-points --data '{"endpoint":"+15551234567","channel":"phone","aiWorkflowId":"<workflow-id>","aiWorkflowVersionId":"<version-id>"}'

Cross-resource patterns

Transfer nodes need a contact. Create a contacts record first, then reference it from a llm-chain-transfer node with {"transferType":"contacts","contactId":"<contact-id>"}. Transfer nodes are terminal — they take no outgoing edges.

Agent nodes derive exit ports from their exit conditions. Each entry in config.exitConditions contributes a port whose id is the exit condition’s id. Edges leaving the node must set source.portId to that same id.

Tools attach at two levels. A top-level tools array on the workflow version is available to every node; a config.tools array on an agent node is scoped to that node. Both hold tool ids.

Common pitfalls

Pitfall	Fix
advancedConfiguration message type spoken is rejected	Use silent, static, or ai_generated.
llmSettings must be object on update	Always send an object, for example {"temperature": 0, "maxTokens": 2000}.
Transfer node has dangling edges	Transfer nodes are terminal, with no output ports.
Layout out of sync after a definition change	Every node and edge id in definition needs a matching layout entry.
Tool never receives parameters	Define aiFields so the agent knows what to extract.

Acting safely

• Commands that spend money or release provisioned infrastructure require --yes. Treat that flag as a decision to confirm with a person, not a formality to pass automatically.
• Validate before writing. --dry-run on publish-workflow and revise-workflow reports what would change without changing anything.
• oneocto flow simulate genuinely executes the workflow, including any tool it reaches. It is a live run, not an offline check.
• Errors go to standard error with a non-zero exit code, so branch on the exit code rather than parsing the success output for failure.

Related pages

• Command Reference - global options, verbs, and command groups
• Flows - the preferred path for building and publishing workflows
• Resources - the resource model and its read-only tables
• Node Reference - what each node type does