alpacon exec

Execute a command directly on a remote server without opening an interactive terminal session. This is useful for running one-off commands, automation scripts, or retrieving output from a server.

alpacon exec [flags] [USER@]SERVER [--] COMMAND...

All flags must be placed before the server name—everything after the server name is treated as the remote command. Use -- to separate the remote command explicitly, so its flags (such as -U or -d) are not interpreted as alpacon flags.

Options

  -h, --help                    help for exec
  -u, --username string         Specify username
  -g, --groupname string        Specify groupname
      --env=KEY[=VALUE]         Set 'KEY' to 'VALUE', or read 'KEY' from the current shell's environment (repeatable)
      --work-session string     Attach this command to a work-session (overrides 'work-session use')
      --detach                  Submit the command and return immediately without waiting
      --wait                    Block and re-attempt until a reviewer approves the sudo request, or the wait times out
      --wait-approval string    Like --wait with a custom wait timeout (e.g. 30m; default 5m); implies --wait
      --output string           Output format: table or json (default "table")

Subcommands

alpacon exec logs JOB_ID    Fetch the result of a command submitted with --detach

Examples

Execute a command on a server:

alpacon exec my-server ls -la /var/log

Execute as a specific user:

alpacon exec admin@my-server cat /etc/hostname
alpacon exec -u admin my-server cat /etc/hostname

Execute with a specific group:

alpacon exec -g developers my-server whoami

Use -- to pass flags to the remote command:

alpacon exec root@db-server -- docker exec postgres psql -U myproject -d myproject
alpacon exec my-server -- grep -r "pattern" /var/log

Run multiple commands—the quotes keep && from being interpreted by your local shell:

alpacon exec my-server -- "df -h && free -m"

Shell metacharacters (;, |, &, $) are interpreted by your local shell first—quote the remote command to send them to the server, where the remote shell interprets them again. To pass one as a literal character, add inner quotes so the remote shell does not interpret it either:

alpacon exec my-server -- "echo 'hello;world'"

Attach the command to a specific work session:

alpacon exec --work-session 11111111-2222-3333-4444-555555555555 my-server -- df -h

Pass an environment variable to the remote command:

alpacon exec --env="KEY1=VALUE1" --env="KEY2=VALUE2" my-server -- printenv KEY1

Read a secret from the current shell without putting it on the command line or in the audit log:

alpacon exec --env="PGPASSWORD" db-server -- psql -h localhost -U app -c 'SELECT 1'

If a secret ends up on the command line anyway—a secret-like KEY=VALUE pair, a password flag (e.g. -pSecret123), or a connection string with an embedded password—the server rejects the command with command_inline_credential before it runs. Move the secret to --env instead.

Asynchronous execution

Use --detach to submit a command and return immediately instead of waiting for it to finish. The CLI prints Job submitted: JOB_ID to stdout (or {"job_id": "..."} with --output json).

alpacon exec --detach web-server -- apt-get update

Retrieve the result later with alpacon exec logs:

alpacon exec logs a1b2c3d4-5678-abcd-ef01-234567890abc

JOB_ID must be a UUID. If the command is still running, the current status is printed and the command exits with code 0—run it again later to check for completion.

Exit codes

The remote command’s exit code is propagated, so alpacon exec exits with the same code as the command it ran on the server.

Exit code 3 indicates the command was denied by the work session gate (for example, no active session or the session does not cover the target server). With --output json, a machine-readable diagnostic is printed to stderr. See Gate errors for the error codes.

Exit code 4 indicates the sudo command is pending human approval. Approve it in the Alpacon console, then re-run—or pass --wait to block until it is approved. With --output json, the CLI emits {"status": "pending_approval", ...} on stdout.

Work session requirement

When you sign in with browser login, alpacon exec requires an active work session that includes the command scope. Token authentication (API token or service token) bypasses this requirement.

The session to attach is resolved from the --work-session flag, the ALPACON_WORK_SESSION environment variable, or the active session set with alpacon work-session use—in that order.

MFA authentication

When executing commands as a system account (e.g., root@my-server), your workspace’s Authentication settings may require additional MFA verification. The CLI MFA flow is the same as alpacon websh—see websh MFA authentication for details.

API token ACLs

When using an API token, the token must have ACL rules for each command you intend to execute. Interactive websh sessions are not restricted by command ACLs, but exec commands always require matching ACL rules.

# Allow the commands this token can run on servers
alpacon token acl command add my-token --command="df *"
alpacon token acl command add my-token --command="cat /etc/hostname"

See Token ACL management for details on wildcard patterns.

Last updated: