---
title: "Run a command"
description: "Run an Alpacon command with an approved work session and account. State its purpose, pass secrets safely, and retrieve results from commands run with detach."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Run a command

Use this procedure when you sign in with `alpacon login`. For automation with a service token, see [service tokens](/use/iam/applications/service-tokens/).

### Request a session

[Request a work session](/use/work-sessions/create/) for your target server with Execute commands (`command`). Wait until its status is **Active**.

### Attach the session

Set the session for your CLI workspace:

```bash
alpacon work-session use WORK_SESSION_ID
```

You 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

```bash
alpacon exec --purpose "Check disk space before deployment" my-server -- df -h
```

Place 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**](/use/audit/events/commands/).

## Choose the account

Use `USER@SERVER` or `-u USER` to select the server account:

```bash
alpacon exec admin@my-server -- whoami
alpacon exec -u admin my-server -- whoami
```

Use the account permitted by the session. An agent session runs only as its approved account; choosing a different account is refused. See [account selection](/use/work-sessions/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:

```bash
alpacon exec purpose JOB_ID "Check disk space before deployment"
```

See [`exec purpose`](/reference/cli/exec/#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:

```bash
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`:

```bash
alpacon exec --detach --purpose "Refresh package metadata" my-server -- apt-get update
alpacon exec logs JOB_ID
```

Submission prints `Job submitted: `. 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](/use/work-sessions/terminal/sudo-with-mfa/). If the command is rejected, open [**Command history**](/use/audit/events/commands/) and read **Rejection reason** before trying again.

Source: https://docs.alpacax.com/use/work-sessions/commands/run/