Command Reference

Every Octo CLI command follows the shape oneocto <verb> <resource> [id] [options], and every command returns JSON.

Global options

These apply to any command.

Option	Description
-v, --version	Print the running CLI version.
-h, --help	Show help for the CLI or for the command it follows.
--pretty	Print prettified JSON, colored when the terminal supports it. This is the default.
--minified	Print minified JSON, suited to piping into another tool.
--tabular	Print rows as an ASCII table.
--output <format>	Set the output format explicitly: pretty, minified, or tabular.

Choose one output format. Combining --minified with --tabular, or either with a conflicting --output, is rejected rather than silently resolved.

Scope options

Most resource commands accept these.

Option	Description
--tenant <slug>	Run against a saved tenant other than the default.
--space-id <id>	Run against a space other than the tenant default.
--query <json>	Sequelize-style JSON for filtering, sorting, and pagination. Available on list and get.
--data <json>	JSON object payload. Available on create and update.
--yes	Confirm a destructive or billable action. Required where the CLI asks for it.

The command model

The canonical CRUD shape covers most day-to-day work:

oneocto list <resource>
oneocto get <resource> <id>
oneocto create <resource> --data '{"...":"..."}'
oneocto update <resource> <id> --data '{"...":"..."}'
oneocto delete <resource> <id> --yes

Two action commands sit alongside the verbs for resources that support them:

oneocto publish <resource> <id> --change-description 'Initial release'
oneocto start-draft <resource> <id>

Run oneocto describe <resource> to confirm which verbs and actions a given resource accepts before you call one.

Querying lists

--query takes a Sequelize-style JSON object, so filtering, ordering, and pagination all travel in one argument:

oneocto list interactions --query '{"where":{"status":"completed"},"order":[["createdAt","DESC"]],"limit":20}'

Key	Purpose
where	Field-matching conditions.
order	Array of [field, direction] pairs.
limit	Maximum rows to return.
offset	Rows to skip, for paging through a large set.

Quote the JSON in single quotes so your shell does not interpret the braces. For a large payload, build the JSON in a file and pass it through jq -c instead of inlining it.

Discovery commands

Command	Description
oneocto about	What the CLI is, its command model, and the resources it knows about.
oneocto resources	Every supported resource with its canonical name, aliases, and verbs.
oneocto describe <resource>	The operational contract for one resource: verbs, fields, examples.
oneocto explain <resource>	Deeper guidance, pitfalls, and related resources.
oneocto authoring [topic]	Workflow authoring guidance. Topics: rules, nodes, templates, conditionals, validate, debug, example.

Command groups

flow

Code-defined procedures for building, publishing, and debugging workflows. See Flows.

oneocto flow list
oneocto flow describe <flow>
oneocto flow scaffold <flow>

execute

Run something directly and get the result back.

Command	Description
execute workflow <id> --data '<event>'	Run a workflow without going through an interaction.
execute interaction <id> -m '<text>'	Send one user message to an existing interaction.
execute start-interaction	Create an interaction with the execution state a plain create interactions does not set up.
execute resume <execution-id>	Resume an execution that is waiting to continue.
execute finalize <id>	Close out an interaction and run post-processing.
execute agent <id> -m '<text>'	Invoke an agent directly with a single message.
execute prompt <id> --data '<vars>'	Run a runnable-prompts record and return the model response.
execute tool --data '<tool+args>'	Test one tool standalone. Returns the full HTTP request and response for rest_api tools.
execute voice	Generate speech audio from text using the configured voice provider.

schedules

Manage cron schedules and keep the external scheduler in step.

Command	Description
schedules create / schedules update <id>	Create or patch a schedule through the scheduler API so the timer is armed immediately.
schedules pause <id> / schedules resume <id>	Stop or re-arm a schedule’s timer.
schedules run <id>	Fire a schedule once now without disturbing its cron timer.
schedules sync <id> / schedules sync-all	Push stored cron and status to the external scheduler.
schedules runs <id>	List recorded runs for one schedule.

Create and update schedules through this group rather than create schedules, so the external timer is updated along with the record.

telephony

Command	Description
telephony search-numbers	Search the provider for purchasable numbers.
telephony purchase-number	Buy a number. This spends money on the billing account.
telephony release-number <id>	Release a number back to the provider. It is not recoverable.
telephony recording-url <id>	Get a time-limited signed URL for a recording’s audio.
telephony twilio-setup / twilio-teardown	Run or tear down provider setup for this tenant.

billing

Command	Description
billing balance	Current spendable credit balance.
billing plan / billing plans	The current plan, and the plans available to select.
billing usage / billing usage-breakdown	A usage summary, or usage broken down by application and source.
billing cards	Saved payment methods.
billing select-plan <plan-id>	Move the tenant onto a plan. This changes what the account is billed.
billing top-up	Buy additional credits. This charges the saved payment method.
billing add-card / confirm-card <setup-id>	Start and complete adding a payment method. Card details are entered in the provider’s own flow, never in the CLI.
billing default-card <id> / remove-card <id>	Manage saved payment methods.

system

Command	Description
system health	Check backend health.
system services-health	Check the health of dependent services.
system ops-bridge-health	Check connectivity to the ops bridge.
system settings [name]	Read settings through the settings API, resolving defaults the raw table does not.
system invite-user	Invite a user to this tenant.

storage

Generic operations that apply to any resource.

oneocto storage bulk create <resource> --data '[...]'
oneocto storage bulk update <resource> --data '[...]'
oneocto storage bulk delete <resource> --data '[...]'
oneocto storage associate <resource> <id> --data '{...}'
oneocto storage create-related <resource> <id> <reference> --data '{...}'

Use storage bulk when you would otherwise loop a single-record verb: it sends one request instead of many.

Output formats

Success output is prettified JSON by default, colored when the terminal supports it.

oneocto list workflows --tabular            # read a list at a glance
oneocto list workflows --minified | jq '.'  # pipe into another tool

--tabular looks for the rows inside the response envelope, so a wrapped list renders as a table without extra flags. A response with no rows prints (no rows).

Errors and exit codes

Failures print to standard error and exit non-zero, so a script can branch on the result.

Outcome	Exit code
Success	0
CLI error, such as a bad option or conflicting output formats	1
API error	1, with the API response body written to standard error

Because errors go to standard error and results go to standard output, piping output stays safe: a failed command pipes nothing rather than piping an error message into your parser.

FAQ

How do I find the options for a subcommand? Use the help verb rather than a trailing flag on a nested command: oneocto flow help publish-workflow.

Why did my --data payload fail to parse? The shell usually consumed the quotes. Wrap the whole JSON argument in single quotes, or build it in a file and pass --data "$(jq -c . payload.json)".

Which commands require --yes? Deleting a record, and anything that spends money or releases provisioned infrastructure — buying or releasing a phone number, topping up credits, removing a saved tenant.

Related pages

• Resources - what the verbs can be pointed at
• Flows - higher-level procedures built on these commands
• Authentication - what --tenant and --space-id override
• Using the CLI from an Agent - discovery order for automated callers