reoclo exec

reoclo exec <serverIdOrName> [options] -- <command...>

Runs an arbitrary command on a server through its runner. Returns the command’s stdout, stderr, and exit code. The CLI exits with the same code the remote command produced, so exec composes cleanly with shell pipelines.

Options

Flag	Default	Description
--timeout <seconds>	600	Hard timeout in seconds (capped at 1800). Must be a positive integer. See Long-running commands.
--cwd <path>	(server-side default)	Working directory for the command.
--env <KEY=VAL>	none	Set an environment variable. Repeatable.
--env-file <path>	none	Load env vars from a dotenv-style file. --env overrides on key collision.
--shell <sh|bash>	(off)	Wrap the command in <shell> -c … so pipes, redirects, and globs are interpreted (see Argument handling).
--no-mask-env	(masking on)	Disable masking of --env/--env-file values in the output.
--scope <scope>	host	Execution scope. host runs on the server. rootless runs inside the rootless docker user namespace if configured.

Why --?

Use -- to separate the CLI’s own flags from the command you want to run. Without it, flags like -l would be interpreted as reoclo flags rather than as arguments to your command.

reoclo exec srv-1 -- ls -lah /var/log
reoclo exec srv-1 -- df -h
reoclo exec srv-1 --cwd /opt/app -- ./scripts/migrate.sh

Argument handling and quoting

By default exec runs your command as argv: each argument after -- is preserved as a single token, even if it contains spaces. The CLI POSIX-quotes each argument so the runner reconstructs them exactly. This means Go-template and other space-containing arguments work without manual wrapping:

# The --format value stays a single argument:
reoclo exec srv-1 -- docker inspect web --format '{{json .State}}'

Shell metacharacters in an argument (|, >, *, …) are passed through literally in this mode. When you actually want a pipeline, redirect, or glob interpreted on the server, use --shell and pass the snippet as one argument:

reoclo exec --shell sh srv-1 -- 'docker ps -q | xargs -r docker inspect --format "{{.Name}}"'

Note: If you write -- sh -c '<script>' yourself, pass the whole script as a single quoted argument. sh -c followed by several separate arguments is almost always a quoting mistake, and the CLI will warn.

Examples

Run a one-shot command:

reoclo exec prod-web-1 -- uptime

Run inside a working directory with environment variables:

reoclo exec prod-web-1 \
  --cwd /opt/myapp \
  --env DEBUG=1 --env LOG_LEVEL=trace \
  -- ./scripts/healthcheck.sh

Capture structured output:

reoclo exec prod-web-1 -o json -- whoami

Use the exit code in CI:

if reoclo exec prod-web-1 -- test -f /var/run/myapp.pid; then
  echo "service is running"
fi

Long-running commands

The CLI waits for the command to finish, up to the full --timeout (600 seconds by default) plus a short margin. It does not give up after 30 seconds.

For a signed-in user, a --timeout above 60 seconds sends the request through the streams host instead of the API host. This keeps a command that runs longer than about 100 seconds from being cut off in transit. Automation keys do not switch hosts.

reoclo exec prod-web-1 --timeout 900 -- ./scripts/backup.sh

Output truncation

The runner caps stdout and stderr at 64 KB per stream to bound memory usage. When output is truncated, the JSON output’s truncated field is true and the text output prints [output truncated] to stderr after the streams.

That cap comes from the runner, not the CLI. The CLI writes everything it receives, including when you pipe the output to another program, such as reoclo api ... | jq. Piped output is not cut at 64 KB.

Automation keys

reoclo exec is one of the few commands available to Automation Keys (alongside apps deploy and apps restart). See CI/CD automation.

Exit codes

The CLI propagates the remote command’s exit code, with the following CLI-specific codes layered on top:

Code	Meaning
0	Command succeeded
1	Command exited 1, or runner relay failure
2	No command given (missing -- <command>), or an invalid --timeout
3	Authentication failure
4	Key type not allowed for this command
5	Server not found
(other)	Whatever exit code the remote command produced

Related

• reoclo apps restart: restart an application’s container
• reoclo logs tail: stream logs from a server source
• reoclo servers: list available servers