---
title: "Run commands"
description: "Run commands on Alpacon servers with exec. Choose the right access method, find command results, and understand input, output, and execution time limits."
---

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

# Run commands

Use `alpacon exec` for commands that can finish without terminal input.

## Choose a command workflow

To check a service, collect output, or run an automation script, start with [Run a command](/use/work-sessions/commands/run/). For a script whose contents need review, use [verified file execution](/use/work-sessions/commands/file-execution/).

## Commands or the web terminal

| What you need | `alpacon exec` | Websh |
| --- | --- | --- |
| Run a command and collect its result | Non-interactive execution; no stdin | An interactive terminal |
| Answer a prompt or use a terminal application | Use Websh instead | Supports terminal input |
| Work-session feature | Execute commands (`command`) | Web terminal (`websh`) |
| AI agent access | An agent work session can run commands | An agent work session cannot include Websh |
| Token authentication | Use a service token for automation | Tokens cannot open an interactive terminal |

See [Websh](/use/work-sessions/terminal/) for interactive work.

## What a command needs

With browser login, select an active [work session](/use/work-sessions/) that includes the target server and the command feature (`command`). Run as an account the session permits. An agent work session runs only as its approved account.

A service token can run non-interactive commands without a work session, subject to its scopes and command ACLs. New personal API tokens cannot hold command-execution or file-transfer scopes. Existing tokens with those scopes keep working without a work session. Use a [service token](/use/iam/applications/service-tokens/) for automation and CI.

## Where results appear

Open [**Command history**](/use/audit/events/commands/) to see the requester, server, account, result, and **Rejection reason**. The work session's **History** tab also shows command entries; expand an entry to read its result. From the CLI, use `alpacon exec ls` to find a command and `alpacon exec logs JOB_ID` to fetch its result.

[Live activity](/use/live-activity/) shows the last 16,384 characters of output while a command runs. The stored result keeps up to 1 MiB; longer output loses its middle, retaining the beginning and end with a truncation marker.

## Limits

| Limit | Value |
| --- | --- |
| Command line | The command line can contain up to 2048 characters. Shorten the command or use verified file execution for a script. |
| Purpose (`--purpose`) | Up to 2000 characters. A longer purpose is refused. Describe the reason for this command within the limit. |
| Script contents (`--file`) | A non-empty UTF-8 script of at most 65,536 bytes (64 KB). Split a larger script or have it read data from a separate file. |
| File execution command line | The interpreter, script path, and arguments together must fit within 2048 characters. Shorten paths or arguments; have the script read bulky input from a file. |
| Live output | Live activity shows the last 16,384 characters. Open the stored command result for more output. |
| Stored result | Up to 1 MiB. Longer output is cut in the middle, keeping the beginning and end. Have the command write a file on the server if you need all of a large result. |
| Run time | A command runs on the server for up to 30 minutes. Split work that cannot finish within 30 minutes. |
| Foreground wait | After 10 minutes without a result following acknowledgment or delivery, foreground exec reports the command as stuck and exits 1. The command keeps running on the server for up to 30 minutes. Use `--detach` and `alpacon exec logs JOB_ID` for work that may take longer than about 10 minutes. |
| CLI status wait (`ALPACON_EXEC_TIMEOUT`) | How long the CLI keeps waiting when it cannot get a running status; default `30m`. Each in-progress status resets this wait. It is not a run-time limit. Check the job before retrying: giving up waiting does not cancel it. |
| Approval wait (`--wait-approval`) | The wait for approval defaults to 5 minutes; accepts a duration such as `30m`. Use `--wait` or set `--wait-approval` when you want the CLI to wait for approval. |

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