Run a command
Use this procedure when you sign in with alpacon login. For automation with a service token, see service tokens.
Request a session
Request a work session for your target server with Execute commands (command). Wait until its status is Active.
Attach the session
Set the session for your CLI workspace:
alpacon work-session use WORK_SESSION_IDYou can instead pass --work-session WORK_SESSION_ID on each command. AI agents must use an agent work session and pass its ID explicitly.
Run the command
alpacon exec --purpose "Check disk space before deployment" my-server -- df -hPlace exec flags before the server name. Everything after the server name is the remote command; -- makes the boundary explicit. Read the result in the CLI or in Command history.
Choose the account
Use USER@SERVER or -u USER to select the server account:
alpacon exec admin@my-server -- whoami
alpacon exec -u admin my-server -- whoamiUse the account permitted by the session. An agent session runs only as its approved account; choosing a different account is refused. See account selection.
State a purpose
--purpose sends context with the command. Explain why you need this action on this server. The limit is 2000 characters; a longer purpose is refused. The audit side panel shows it under Stated purpose.
If your workspace asks for a purpose, the command can wait at Awaiting purpose and the CLI exits 7. Answer for the same job:
alpacon exec purpose JOB_ID "Check disk space before deployment"See exec purpose for the response window and behavior.
Pass secrets as environment variables
Keep credentials out of the command line. If PGPASSWORD is already set in your local shell, pass its name:
alpacon exec --env="PGPASSWORD" db-server -- psql -h localhost -U app -c 'SELECT 1'The CLI reads the value from your environment. Do not print the variable in the remote command. Commands containing inline credentials are refused; --env is for command-line execution and cannot be combined with --file.
Long-running commands
For anything that may take longer than about 10 minutes, submit it with --detach:
alpacon exec --detach --purpose "Refresh package metadata" my-server -- apt-get update
alpacon exec logs JOB_IDSubmission prints Job submitted: <JOB_ID>. Replace JOB_ID with that UUID when checking the result. A foreground alpacon exec reports a command as stuck and exits 1 after 10 minutes without a result following acknowledgment or delivery. The command keeps running on the server for up to 30 minutes, so a failed foreground wait is not a reason to submit it again.
exec logs result | Exit code | Next step |
|---|---|---|
| Still running or queued | 0 | Check the same job again later; 0 does not mean it finished |
| Awaiting purpose, if your workspace asks for one | 7 | Answer with alpacon exec purpose JOB_ID PURPOSE |
| Awaiting approval | 4 | Have an approver decide in the console |
| Rejected | 6 | Read the rejection before submitting another command |
| Stuck, error, or cancelled | 1 | Check the status and details in Command history |
| Finished | Remote command’s exit code | Read the output and exit code |
Commands have a 30-minute run-time limit on the server. A command that reaches it returns exit 124 with Command timed out after 30m0s. Split longer work into commands that each finish within the limit.
ALPACON_EXEC_TIMEOUT
ALPACON_EXEC_TIMEOUT controls how long the CLI keeps waiting when it cannot get a running status. Its default is 30m; it accepts durations such as 1h. Every in-progress status resets this wait. It does not extend the server’s run-time limit or prevent the foreground stuck result.
If this wait expires, the CLI prints Error: [client_timeout] CLI gave up waiting for the server to report a result and exits 1. The command is not cancelled. Check alpacon exec logs JOB_ID before deciding whether to retry.
When a command waits for approval
A command at Awaiting approval is held for a person to decide in the console. The CLI exits 4 unless you wait with --wait or --wait-approval 30m; the default approval wait is 5 minutes. The held command runs automatically if approved, so do not submit it again while it waits.
For sudo approval and terminal authentication, see sudo with MFA. If the command is rejected, open Command history and read Rejection reason before trying again.