Skip to main content

roboctl

roboctl drives your workspace from a terminal — robots, flows, jobs, schedules, users, licences, audit — plus the package and skill authoring workflow.

Three CLIs, three jobs

Easy to confuse, so worth stating once:

roboctlManages the workspace over the API. This page.
robomotion-deskbotIs the robot. Connects to a workspace and executes flows.
robomotion-agentConnects the machine so the Designer can reach it for screen capture and image nodes.

roboctl never runs a flow itself; it asks a robot to.

Global flags​

FlagShortDescription
--config-cConfig file. Defaults to ~/.robomotion/config.yaml.
--api-url-uOverride the API endpoint. Needed for On-Prem and Private Cloud — point it at your own domain plus /api.
--access-token-tAPI token, if you would rather not use a stored context.
--contextWhich stored authentication context to use.

Getting signed in​

roboctl auth init                 # store a context
roboctl auth list                 # list stored contexts
roboctl auth set-context acme     # choose the default

A context is a named workspace plus token, so you can hold several and switch between them — the usual case being a production and a test workspace.

# On-Prem or Private Cloud
roboctl --api-url https://robomotion.acme.inc/api auth init
Tokens on the command line

--access-token is visible to every user on the machine through ps. Prefer a stored context, and in CI prefer an environment variable over an argument.

Workspace commands​

Robots​

roboctl robots list
roboctl robots create --name Finance-Bot-01 --type production
roboctl robots update ...
roboctl robots stop ...
roboctl robots delete ...

--type is development, production or ondemand. Anything else is silently treated as development, so check your spelling. See Robot for what each type can do.

Flows​

roboctl flows list
roboctl flows run ...
roboctl flows delete ...

flows run dispatches a run to a robot. The robot must be connected — see the FAQ on why.

Jobs, schedules, users, licences, audit​

roboctl jobs list
roboctl schedules list
roboctl users invite ...
roboctl licenses list
roboctl audit ...

These mirror the API endpoints of the same name, so the API Playground is the place to see the exact parameters and response shapes.

Package authoring​

Scaffold a package from an OpenAPI specification​

This is the feature most people do not know exists, and it is the fastest route from "this service has a REST API" to "this service has Robomotion nodes".

roboctl create --from openapi.yaml

Given an OpenAPI document, it generates a package: node definitions, HTTP plumbing, config.json, credential scaffolding, an icon and a module. You then refine what it produced rather than writing it from nothing.

shape of a document it accepts.

Build and publish​

roboctl skill package             # package for distribution
roboctl skill build ./mypackage   # build it
roboctl skill index ./repo        # generate a repository index
roboctl skill list                # what is installed

Repositories​

roboctl repo ...                  # register and manage package repositories
roboctl skill install <REPO_URL>
roboctl skill uninstall <INSTALL_ID>

Repositories are how a team distributes its own packages without publishing them publicly. The Admin Console side is Repositories.

Agent authoring​

roboctl agent prepare-credentials ./myagent

Prepares the credential set an agent needs before it is published. See AI Agents, Skills and MCP.

Version​

roboctl version

Using it in CI​

The combination worth knowing: a stored context is convenient interactively, but in a pipeline you want no state on disk.

# Publish and run, with no context file
export ROBOMOTION_TOKEN=...       # from your CI secret store
roboctl --api-url "$RM_API" --access-token "$ROBOMOTION_TOKEN" flows list

For anything more involved, call the API directly — it is the same surface, and the playground will give you the request in your language.

Next​