# Reoclo CLI Usage > reoclo-cli-usage: Operate Reoclo from the CLI - Skill: `reoclo/reoclo-cli-usage` (Agent Skill) - Install (CLI): `npx skillmds@latest add reoclo/reoclo-cli-usage` - Raw SKILL.md: https://api.skillmd.com/api/skills/reoclo/reoclo-cli-usage/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: reoclo (https://skillmd.com/u/reoclo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/reoclo/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 ```bash 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 ```bash 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 ` 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) | Flag | Effect | |------|--------| | `-o, --output ` | output format; use `json` for scripting | | `--quiet` | suppress non-error output | | `--verbose` | log HTTP requests (tokens redacted) | | `--no-color` | disable ANSI colors | | `--profile ` | use a named profile (multi-account/multi-env); equivalent to `$REOCLO_PROFILE` | | `--org ` | run against this organization for one invocation; wins over `$REOCLO_ORG` and `.reoclo` | ## Command map Every top-level command group. Drill in with ` --help`. | Group | Purpose | |-------|---------| | `login` / `logout` / `whoami` | authenticate, sign out, show identity | | `org` | list granted organizations (`ls`); print this directory's target (`current`) | | `profile` | manage named profiles (accounts / environments) | | `keyring` | move stored tokens between config.json and the OS keyring | | `servers` | list, inspect, rename servers; health, ports, uptime, reboot; cloud `power` | | `containers` | fleet containers: list, inspect, logs, restart, recreate, scale, labels | | `apps` | list, inspect, deploy, restart apps; manage deployment `config` | | `groups` | definition groups (stacks): coordinated compose deployments and one-shot tasks; `stacks` is an alias | | `deployments` | deployment history, details, stages, build/runtime logs | | `logs` | tail, search, systemd journal, sources, storage stats and usage | | `env` | application environment variables (write-only values) | | `domains` | register, verify, and health-check domains | | `verified-domains` | verified root domains: claim, prove ownership, list attached resources | | `secrets` | secret projects, keys, reveal, set, import, inject, bind to apps/stacks | | `run` | resolve granted secrets and run a command with them as env vars | | `monitors` | uptime monitors | | `status-pages` | public status pages and their `components` | | `incidents` | incidents and incident updates | | `alerts` | alert instances, ack/resolve, mutes, routing, catalog | | `channels` | notification channels (Slack, Discord, and so on) | | `repos` | mirrored git repositories | | `providers` | git providers (GitHub, Gitea): connect, sync, status | | `registry` | container registry credentials; docker login/logout on a server | | `schedule` | scheduled operations: create, list, pause, trigger, runs | | `audit` | organization audit log | | `dashboard` | organization summary (counts, recent activity, deploys) | | `exec` / `shell` | run one-shot commands or an interactive shell on a server | | `tunnel` | TCP/UDP tunnels through a runner | | `checkout` / `deploy` | CI helpers: clone a repo on a server, external deploy sync | | `init` | link this project to an organization and install reoclo skills | | `skills` | install, list, and update reoclo agent skills without re-running `init` | | `api` | raw authenticated API request (escape hatch for endpoints without a command) | | `sync` | refresh this profile's cached capabilities from the server (no re-login) | | `mcp` | start the stdio MCP server | | `completion` | shell completion for bash, zsh, fish | | `upgrade` | self-update the CLI | 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 ```bash reoclo servers ls # slug, name, hostname, IP, status, runner reoclo servers get # full record reoclo servers metrics # latest CPU / RAM / disk from the runner reoclo servers health # health state reoclo servers ports # listening ports + firewall reoclo servers uptime # connectivity uptime (--hours) reoclo servers containers # containers running on this server reoclo servers set-slug # rename the slug reoclo servers reboot # 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. ```bash reoclo servers power capabilities # what this provider supports reoclo servers power status # live power state reoclo servers power on reoclo servers power off --yes # hard power cut; --yes skips the prompt reoclo servers power shutdown # graceful shutdown reoclo servers power reboot # provider reboot (not the runner reboot) reoclo servers power reset # hard reset ``` Add `--wait` to block until the server reaches its target state (for example `reoclo servers power off --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. ```bash reoclo exec -- docker ps # use -- to separate the remote command reoclo exec --shell bash -- 'docker ps | wc -l' # pipes/redirects/globs reoclo exec --env-file .env.prod -- ./migrate.sh # inject env (masked in output) reoclo shell # interactive shell ``` ## Containers (fleet) Cross-server container operations. Target a container by ` `. ```bash reoclo containers ls # fleet containers (filters via --help) reoclo containers refresh # trigger a fleet snapshot refresh reoclo containers inspect # config + env (masked by default) reoclo containers logs # fetch or follow (--follow) reoclo containers restart reoclo containers recreate # new env/labels/ports (see --help) reoclo containers scale # scale a Swarm service reoclo containers labels # patch labels (see --help) ``` ## Applications and deployments ```bash reoclo apps ls # incl. a CI column: the app's CI gate state reoclo apps get reoclo apps deploy # trigger a deployment (--ref , --wait, --force-recreate) reoclo apps restart # restart the backing container reoclo apps logs # container logs for the app reoclo apps config --help # manage deployment config reoclo deployments ls # organization deployment history (--app to filter) reoclo deployments get # full details incl. build stages reoclo deployments stages # pipeline stages with status and duration reoclo deployments logs --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`. ```bash reoclo groups ls # kind, member count, CI gate, last deploy reoclo groups get # incl. deploy branch, CI gate, compose path reoclo groups deploy --wait # coordinated deploy of every managed member (--force-recreate) reoclo groups redeploy # redeploy one compose service only (--force-recreate) reoclo groups run --wait # run a one-shot task member (compose run --rm) reoclo groups task-runs # one-shot run history (status, exit code) reoclo groups deployments # coordinated deployment history reoclo groups deployment --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 ```bash reoclo logs tail --server --source container --name # fetch or follow (--follow) reoclo logs search # across servers and sources reoclo logs system # systemd journal reoclo logs sources # containers + systemd units available reoclo logs stats # tenant-wide storage totals + per-server reoclo logs usage # storage and retention ``` ## Env vars ```bash 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 ```bash reoclo domains ls reoclo domains get reoclo domains add # then: reoclo domains verify # TXT record to add reoclo domains dns # DNS records + verification status reoclo domains health # DNS + TLS + uptime reoclo domains rm # 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. ```bash reoclo verified-domains ls reoclo verified-domains get reoclo verified-domains resources # domains, apps, status pages under this root reoclo verified-domains add # claim + start verification reoclo verified-domains verify # the TXT record that proves ownership reoclo verified-domains rm ``` ## 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). ```bash reoclo secrets projects --help # manage secret projects reoclo secrets ls --project # list keys in a project reoclo secrets get --project # reveal a value reoclo secrets set --project # create or update reoclo secrets rm --project 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:////`: it maps to the secret `` in project `` (`` 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: ```bash 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 # list bindings + key selections reoclo secrets unbind --app # a unique id prefix is enough ``` Exactly one target: `--app ` or `--group `. `--key ` is repeatable (omit it to inject every key), `--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 ```bash reoclo monitors ls | get | create | update | pause | resume | rm reoclo status-pages ls | get | create | update | rm reoclo incidents ls | get | create | update | add-update ``` `reoclo incidents update --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`: ```bash reoclo status-pages components ls reoclo status-pages components get reoclo status-pages components add # name, order, visibility, checks reoclo status-pages components update reoclo status-pages components pin # override the derived status reoclo status-pages components unpin reoclo status-pages components reorder reoclo status-pages components rm ``` ## Alerts and notification channels ```bash reoclo alerts list # alert instances (filters via --help) reoclo alerts get # with severity history reoclo alerts ack reoclo alerts resolve 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 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 # for example: slack, discord reoclo channels test # send a test notification reoclo channels enable | disable | update | delete ``` ## Git repos, providers, and registries ```bash reoclo repos ls | get | branches reoclo providers ls | get reoclo providers connect # start OAuth (opens browser) reoclo providers sync # queue a repo sync reoclo providers status # sync status reoclo providers test # connection / refresh-token health reoclo registry ls | get | create | update | rm reoclo registry test # test a connection (ad-hoc) reoclo registry login # docker login on a managed server (CI) reoclo registry logout ``` ## Scheduled operations ```bash reoclo schedule ls reoclo schedule get reoclo schedule create --help # cron-style operations reoclo schedule update | pause | resume | rm reoclo schedule trigger # run now reoclo schedule runs # list runs reoclo schedule run # show one run ``` ## Audit and dashboard ```bash 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): ```bash reoclo tunnel -L 5432:5432 # forward localhost:5432 to server's 127.0.0.1:5432 reoclo tunnel -L 8080:internal-db:5432 # forward to a different remote host reoclo tunnel -R 8080:3000 # reverse: server's :8080 to your localhost:3000 reoclo tunnel -L 53:53 --udp # UDP reoclo tunnel ls # live + historical sessions reoclo tunnel close ``` 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). ```bash 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: ```bash 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: ```bash 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: ```bash reoclo checkout # clone or update a git repo on a managed server reoclo deploy sync --help # external deploy sync reoclo registry login # 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: ```bash 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//` (read by Codex, Gemini, opencode, and Cursor) with a `.claude/skills/` link for Claude Code. `skills update` only refreshes what is already installed and never adds new skills. ## MCP server ```bash reoclo mcp --org # 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 ` 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. ```bash 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 -f name=web-2 -f cores=4 # JSON body fields; body implies POST reoclo api -X PATCH --raw-field note=123 # --raw-field keeps the value a string reoclo api -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 `$(...)`. ```bash 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 ```bash 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.