Reoclo CLI Usage

reoclo-cli-usage: Operate Reoclo from the CLI

Overview

reoclo is the command-line client for the Reoclo platform. It manages servers, applications, containers, deployments, logs, domains, secrets, monitoring, and more from your terminal. rc is a built-in short alias for reoclo. This skill covers using the released CLI; it is not about building the CLI itself.

Every command level supports --help (for example reoclo servers --help, reoclo apps deploy --help). Use it to see the exact flags for any command. This skill lists what exists and how the pieces fit; --help is the source of truth for flags.

Install and update

curl -sSL https://get.reoclo.com/cli | bash     # macOS / Linux
brew install reoclo/tap/reoclo                   # Homebrew
reoclo upgrade                                   # self-update (--check to dry-run)

The binary is self-contained (no Node or Bun runtime needed).

First run

reoclo login          # OAuth device flow (opens a browser; --no-browser to print the URL)
reoclo whoami         # confirm identity + how many organizations are granted
reoclo org ls         # organizations your credential can access
reoclo org current    # the organization commands in this directory will target
reoclo logout         # remove stored credentials (defaults to the active profile)

Org-scoped commands need an explicit organization. There is no persistent "active org" to switch. Select one per invocation with the global --org <slug> flag or $REOCLO_ORG, or bind the directory once with reoclo init (writes a .reoclo file). With none of the three set, an org-scoped command fails and tells you how to select one.

Global flags (work on every command)

Command map

Every top-level command group. Drill in with <group> --help.

Most commands accept either a resource id or its slug. Slugs are the recommended, stable identifier and are what tab completion offers.

The collection verbs are interchangeable everywhere: ls and list are the same command, and so are rm, delete, and remove. Whichever spelling you try, the group answers.

Servers

reoclo servers ls                          # slug, name, hostname, IP, status, runner
reoclo servers get <idOrSlug>              # full record
reoclo servers metrics <idOrSlug>          # latest CPU / RAM / disk from the runner
reoclo servers health <idOrSlug>           # health state
reoclo servers ports <idOrSlug>            # listening ports + firewall
reoclo servers uptime <idOrSlug>           # connectivity uptime (--hours)
reoclo servers containers <idOrSlug>       # containers running on this server
reoclo servers set-slug <idOrSlug> <slug>  # rename the slug
reoclo servers reboot <idOrSlug>           # OS reboot via the runner (--yes to skip prompt)

Server power (cloud)

For cloud-managed servers, drive the provider's power controls. These work only where the server has a cloud provider and credentials configured, and only for operations that provider supports (check with capabilities). This is separate from reoclo servers reboot, which reboots the OS through the runner.

reoclo servers power capabilities <server>   # what this provider supports
reoclo servers power status <server>         # live power state
reoclo servers power on <server>
reoclo servers power off <server> --yes      # hard power cut; --yes skips the prompt
reoclo servers power shutdown <server>       # graceful shutdown
reoclo servers power reboot <server>         # provider reboot (not the runner reboot)
reoclo servers power reset <server>          # hard reset

Add --wait to block until the server reaches its target state (for example reoclo servers power off <server> --wait), giving up after --wait-timeout seconds (default 120). off, shutdown, reboot, and reset prompt for confirmation unless you pass --yes.

Running commands and shells on a server

Runs over the server's runner. No inbound SSH needed.

reoclo exec <server> -- docker ps                          # use -- to separate the remote command
reoclo exec --shell bash <server> -- 'docker ps | wc -l'   # pipes/redirects/globs
reoclo exec --env-file .env.prod <server> -- ./migrate.sh  # inject env (masked in output)
reoclo shell <server>                                      # interactive shell

Containers (fleet)

Cross-server container operations. Target a container by <server> <name>.

reoclo containers ls                              # fleet containers (filters via --help)
reoclo containers refresh                         # trigger a fleet snapshot refresh
reoclo containers inspect <server> <name>         # config + env (masked by default)
reoclo containers logs <server> <name>            # fetch or follow (--follow)
reoclo containers restart <server> <name>
reoclo containers recreate <server> <name>        # new env/labels/ports (see --help)
reoclo containers scale <server> <name> <n>       # scale a Swarm service
reoclo containers labels <server> <name>          # patch labels (see --help)

Applications and deployments

reoclo apps ls                         # incl. a CI column: the app's CI gate state
reoclo apps get <idOrSlug>
reoclo apps deploy <idOrSlug>          # trigger a deployment (--ref <git-ref>, --wait, --force-recreate)
reoclo apps restart <idOrSlug>         # restart the backing container
reoclo apps logs <idOrSlug>            # container logs for the app
reoclo apps config --help              # manage deployment config

reoclo deployments ls                  # organization deployment history (--app to filter)
reoclo deployments get <id>            # full details incl. build stages
reoclo deployments stages <id>         # pipeline stages with status and duration
reoclo deployments logs <id> --build   # build stage logs

For deployments get and deployments logs, the deployment id alone is enough. --app stays accepted for scripts that already pass it.

Stacks (definition groups)

A stack is a definition group: one docker-compose file, one member application for each service, one coordinated deployment. reoclo stacks is an alias for reoclo groups.

reoclo groups ls                              # kind, member count, CI gate, last deploy
reoclo groups get <group>                     # incl. deploy branch, CI gate, compose path
reoclo groups deploy <group> --wait           # coordinated deploy of every managed member (--force-recreate)
reoclo groups redeploy <group> <service>      # redeploy one compose service only (--force-recreate)
reoclo groups run <group> <service> --wait    # run a one-shot task member (compose run --rm)
reoclo groups task-runs <group>               # one-shot run history (status, exit code)
reoclo groups deployments <group>             # coordinated deployment history
reoclo groups deployment <group> <numberOrId> --logs   # stages, per-service slices, log tails

--wait polls until the deployment or task finishes and exits non-zero on failure (--wait-timeout seconds, default 600). A one-shot task is a compose service under profiles: (a migration, for example). Deploy the stack one time before you run a task: the run uses the env files from the last stack deployment.

--force-recreate recreates containers even when the image and configuration did not change. Without it, a compose deploy leaves unchanged services running. Use it to restart a stack from a clean state, or to redeploy one unchanged service. On groups redeploy the recreate applies only to the named service.

Logs

reoclo logs tail --server <server> --source container --name <name>   # fetch or follow (--follow)
reoclo logs search <query>            # across servers and sources
reoclo logs system <server>           # systemd journal
reoclo logs sources <server>          # containers + systemd units available
reoclo logs stats                     # tenant-wide storage totals + per-server
reoclo logs usage                     # storage and retention

Env vars

reoclo env ls                              # keys only; values are write-only via the API
reoclo env set KEY=value [KEY2=value2 ...]
reoclo env rm KEY

A successful env set does not redeploy the application. The new values apply on the next deploy.

Domains

reoclo domains ls
reoclo domains get <fqdnOrId>
reoclo domains add <fqdn>                  # then:
reoclo domains verify <fqdnOrId>           # TXT record to add
reoclo domains dns <fqdnOrId>              # DNS records + verification status
reoclo domains health <fqdnOrId>           # DNS + TLS + uptime
reoclo domains rm <fqdnOrId>               # decommission

Root-domain ownership is separate from per-FQDN registration. verified-domains claims a root (for example example.com) and proves ownership with one TXT record. Domains you then add under a verified root verify automatically.

reoclo verified-domains ls
reoclo verified-domains get <rootOrId>
reoclo verified-domains resources <rootOrId>   # domains, apps, status pages under this root
reoclo verified-domains add <rootDomain>       # claim + start verification
reoclo verified-domains verify <rootOrId>      # the TXT record that proves ownership
reoclo verified-domains rm <rootOrId>

Secrets and run

Secrets live in projects. run injects the secrets a credential is granted into a child process as env vars. run --env-file and secrets inject render a .env template of op:// references, resolving each value from Reoclo (a drop-in for 1Password's op inject, and the op binary is not needed).

reoclo secrets projects --help         # manage secret projects
reoclo secrets ls --project <name>     # list keys in a project
reoclo secrets get <key> --project <name>   # reveal a value
reoclo secrets set <key> --project <name>   # create or update
reoclo secrets rm <key> --project <name>
reoclo secrets import --help           # import from an external source
reoclo secrets inject -i app.env.tpl -o app.env   # render an op:// template to a file (op inject drop-in)

reoclo run -- ./my-app                 # run with granted secrets injected as env vars
reoclo run --env-file app.env.tpl -- ./my-app   # inject only the op:// refs a template names

An op:// reference is op://<project>/<item>/<field>: it maps to the secret <field> in project <project> (<item> is ignored). secrets inject accepts an automation key or a login session. run needs an automation key.

Bind secrets to apps and stacks

bind links a secret project to an application or a stack, so the project's secrets inject as env vars at deploy time:

reoclo secrets bind infra --app api                     # every key in the project
reoclo secrets bind storage --group portfolio \
    --key MINIO_ROOT_USER --key MINIO_ROOT_PASSWORD     # selected keys, into a stack
reoclo secrets bind storage --app public-web \
    --key MINIO_ROOT_USER=S3_ACCESS_KEY_ID              # rename on bind

reoclo secrets bindings --app <app>                     # list bindings + key selections
reoclo secrets unbind <bindingId> --app <app>           # a unique id prefix is enough

Exactly one target: --app <idOrSlug> or --group <idOrSlug>. --key <KEY[=NEW_NAME]> is repeatable (omit it to inject every key), --prefix <PREFIX_> prefixes un-renamed keys, and --scope is production, preview, or both (default production). A stack-level binding injects into every member. To give one member only part of a project, bind that member with --app and --key. Bindings apply on the next deploy.

Monitoring: monitors, status pages, incidents

reoclo monitors ls | get <id> | create | update <id> | pause <id> | resume <id> | rm <id>
reoclo status-pages ls | get <id> | create | update <id> | rm <id>
reoclo incidents ls | get <id> | create | update <id> | add-update <id>

reoclo incidents update <id> --state resolved resolves an incident. Use --help on create / update for the field flags.

Status pages are built from components. Manage them under status-pages components:

reoclo status-pages components ls <page>
reoclo status-pages components get <page> <component>
reoclo status-pages components add <page>              # name, order, visibility, checks
reoclo status-pages components update <page> <component>
reoclo status-pages components pin <page> <component>  # override the derived status
reoclo status-pages components unpin <page> <component>
reoclo status-pages components reorder <page> <components...>
reoclo status-pages components rm <page> <component>

Alerts and notification channels

reoclo alerts list                     # alert instances (filters via --help)
reoclo alerts get <instance-id>        # with severity history
reoclo alerts ack <instance-id>
reoclo alerts resolve <instance-id>
reoclo alerts history                  # recently resolved
reoclo alerts mute [alert-code]        # mute a code for a resource (omit code to mute all)
reoclo alerts mutes                    # manage mutes
reoclo alerts unmute <mute-id>
reoclo alerts routing --help           # manage alert routing
reoclo alerts catalog --help           # manage the alert catalog

reoclo channels list
reoclo channels kinds                  # available provider kinds
reoclo channels create <kind>          # for example: slack, discord
reoclo channels test <id>              # send a test notification
reoclo channels enable <id> | disable <id> | update <id> | delete <id>

Git repos, providers, and registries

reoclo repos ls | get <repo> | branches <repo>

reoclo providers ls | get <provider>
reoclo providers connect <provider>    # start OAuth (opens browser)
reoclo providers sync <provider>       # queue a repo sync
reoclo providers status <provider>     # sync status
reoclo providers test <provider>       # connection / refresh-token health

reoclo registry ls | get <id> | create | update <id> | rm <id>
reoclo registry test                   # test a connection (ad-hoc)
reoclo registry login <serverId>       # docker login on a managed server (CI)
reoclo registry logout <serverId>

Scheduled operations

reoclo schedule ls
reoclo schedule get <id>
reoclo schedule create --help          # cron-style operations
reoclo schedule update <id> | pause <id> | resume <id> | rm <id>
reoclo schedule trigger <id>           # run now
reoclo schedule runs <id>              # list runs
reoclo schedule run <id> <runId>       # show one run

Audit and dashboard

reoclo audit ls                        # organization audit log (filters via --help)
reoclo dashboard                       # org summary: counts, recent activity, deploys

Tunnels

Authenticated TCP/UDP tunnels through a server's runner (no SSH keys, no inbound firewall rules):

reoclo tunnel <server> -L 5432:5432                 # forward localhost:5432 to server's 127.0.0.1:5432
reoclo tunnel <server> -L 8080:internal-db:5432     # forward to a different remote host
reoclo tunnel <server> -R 8080:3000                 # reverse: server's :8080 to your localhost:3000
reoclo tunnel <server> -L 53:53 --udp               # UDP
reoclo tunnel ls                                    # live + historical sessions
reoclo tunnel close <tunnelId>

Tunnels survive transient runner reconnects (parked, then resumed).

Profiles

Each profile holds its own credential, so profiles let you switch between accounts and environments (for example prod vs. staging). Organization selection is separate and per-invocation (--org, $REOCLO_ORG, or the .reoclo binding; see First run).

reoclo profile ls                          # list configured profiles
reoclo login --profile staging             # create / authenticate a profile
reoclo profile use staging                 # set the default profile persistently

Select a profile per-invocation two ways, both honored by every command:

reoclo --profile staging servers ls        # global flag (works before or after the subcommand)
REOCLO_PROFILE=staging reoclo servers ls   # env var (handy to export for a shell session)

Precedence: --profile flag, then $REOCLO_PROFILE, then the active profile from reoclo profile use.

reoclo sync refreshes the profile's cached capabilities from the server without a re-login. Run it when the server has granted the credential new permissions and a command still reports them missing.

Keyring

By default the CLI stores tokens in the OS keyring. Move them if you need to:

reoclo keyring status
reoclo keyring migrate    # config.json -> OS keyring (--profile, else all)
reoclo keyring export     # OS keyring -> config.json

CI and automation credentials

Automation keys are scoped to a fixed command set: apps deploy, apps restart, exec, shell, checkout, registry login, registry logout, deploy sync, run, and secrets inject. Everything else needs an interactive org login.

CI helpers:

reoclo checkout <serverId>             # clone or update a git repo on a managed server
reoclo deploy sync --help              # external deploy sync
reoclo registry login <serverId>       # docker login on a managed server

Agent skills

reoclo init links a project to an organization and offers to install reoclo agent skills. The skills group manages them on their own:

reoclo skills install    # pick skills, detect agent harnesses (`skills init` is an alias)
reoclo skills list       # skills available in the reoclo/skills repo + which are installed
reoclo skills update     # refresh already-installed skills to the latest, in place

Skills install to .agents/skills/<name>/ (read by Codex, Gemini, opencode, and Cursor) with a .claude/skills/<name> link for Claude Code. skills update only refreshes what is already installed and never adds new skills.

MCP server

reoclo mcp --org <slug>                # start the stdio MCP server (for MCP-capable agents)

Like every org-scoped command, mcp needs an organization or it exits immediately with a selection error. In an MCP client config, put --org <slug> in the command arguments. Starting it from a directory with a .reoclo binding also works.

Raw API access

When no command covers an endpoint, reoclo api sends an authenticated request and prints the JSON response (in the spirit of gh api). It rides the same profile auth and base URL as every other command, and {tenant} in the path expands to the current organization's tenant id.

reoclo api '/tenants/{tenant}/secret-projects'           # GET is the default
reoclo api '/tenants/{tenant}/servers/' -q page=2        # -q key=value appends query params
reoclo api <path> -f name=web-2 -f cores=4               # JSON body fields; body implies POST
reoclo api <path> -X PATCH --raw-field note=123          # --raw-field keeps the value a string
reoclo api <path> -X PUT --data @body.json               # raw JSON body (@file, or - for stdin)

-f auto-types true, false, null, and numbers. --data cannot combine with -f/--raw-field.

Scripting

Most commands honor -o json|yaml for piping. Two things to know:

• List commands emit one JSON object per line (NDJSON), not a JSON array. Filter each line directly with jq -r '.field', not jq '.[]' (which yields nothing).
• reoclo secrets get prints the bare secret value and ignores -o, so it composes with $(...).

reoclo servers ls -o json | jq -r 'select(.status=="active") | .slug'
reoclo apps ls -o yaml
VALUE=$(reoclo secrets get DB_PASSWORD --project prod)   # raw value, not JSON

Shell completion

reoclo completion install        # detects your shell, writes + wires the completion file
reoclo completion bash           # or print a shim for bash | zsh | fish

Resource completion is cache-only: it reads slugs from the local cache that reoclo servers ls / reoclo apps ls populate. Run any ls once on a fresh install to warm it.

Tips

• Stuck on a subcommand? Every level supports --help.
• Most commands accept either a resource id or its slug.
• Use -o json for anything you script; text output is for humans.