---
title: "alpacon work-session create"
description: "Create a new Alpacon work session from the CLI. Request scopes and servers, set the duration, wait for approval, and attach the session automatically."
---

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

# alpacon work-session create

Create a work session with the servers, scopes, and duration your task needs.

## Usage

`alpacon work-session create [flags]`

## Key facts

- In non-interactive mode, provide `--purpose`, `--server`, `--scope`, and an expiry.
- Use either `--expires-in` or `--expires-at`, never both.
- Combine `--wait --use` to attach a user session after approval.
- Declare sudo command patterns with `--sudo` for non-interactive sudo.

## Flags

### Request

| Flag | Type | Description |
| --- | --- | --- |
| `--purpose` | `string` | Describe what you are doing and why. Markdown supported; required in non-interactive mode. |
| `--server` | `strings` | Target server names. Repeat the flag or separate names with commas. |
| `--scope` | `strings` | Allowed: `command`, `editor`, `sudo`, `tunnel`, `webftp`, `websh`. Repeat the flag or use commas; agent sessions cannot request `websh`. |
| `--expires-in` | `string` | Relative duration, such as `1h`, `2h`, or `4h`. Choose this or `--expires-at`. |
| `--expires-at` | `string` | Absolute expiry in RFC3339 format. Choose this or `--expires-in`. |

### Approval and attach

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `--wait` | `bool` | Wait for approval, then exit. The timeout is 5 minutes; combine with `--use` to attach. | `false` |
| `--wait-approval` | `string` | Custom approval wait timeout, such as `30m`. Implies `--wait`; the usual wait timeout is `5m`. | — |
| `--use` | `bool` | Set the session as active once its status is `active`. Combine with `--wait` when approval is required. Unavailable for agent sessions. | `false` |

### Account and sudo

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `--account` | `string` | Server account shown to the approver, such as `root`. Use the same account with `-u ACCOUNT` on later commands. | — |
| `--requester-type` | `string` | Allowed: `user`, `agent`. A detected AI agent always uses `agent`; use `AI_AGENT=NAME` for an agent the CLI does not detect. | `user` |
| `--sudo` | `stringArray` | Repeatable, comma-separated sudo patterns for non-interactive `exec`. Adds the `sudo` scope; policies are submitted for approval. See [pattern rules](#sudo-command-patterns). | — |
| `--sudo-reason` | `string` | Justification for the policies declared with `--sudo`. | — |

### Help and output

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `-h`, `--help` | `bool` | Show command help. | `false` |
| `--output` | `string` | Output format: `table` or `json`. Inherited from the root command. | `table` |

## Examples

Request a session for command execution and terminal access

```bash
alpacon work-session create --purpose "nginx fix" --scope command,websh --server web-01 --expires-in 2h
```

Request a session for multiple servers with an absolute expiry, and wait for approval

```bash
alpacon work-session create --purpose "deploy" --scope command --server web-01,db-01 --expires-at 2027-01-15T10:00:00Z --wait
```

Create a session and set it as the active session in one step

```bash
alpacon work-session create --purpose "deploy" --scope command --server web-01 --expires-in 2h --wait --use
```

Pre-declare sudo command patterns for non-interactive sudo

```bash
alpacon work-session create --purpose "nginx hotfix" --scope sudo --server web-01 --expires-in 2h \
  --sudo "systemctl restart nginx,systemctl reload nginx" --sudo "tail -f /var/log/nginx/*.log"
```

Name the account the work runs as

```bash
alpacon work-session create --purpose "restart nginx" --scope command,sudo --server web-01 --expires-in 1h --account root
```

The session starts in the **pending** state and becomes usable once approved. Superusers' own requests are approved automatically, except sessions an AI agent requests, which by default wait for a person's approval unless the workspace is in Advisory mode. See the [lifecycle](/reference/cli/work-session/#lifecycle) and [Request a session](/use/work-sessions/create/) for details.

## Sudo command patterns

`--sudo` patterns decide which elevated commands the session can run without an interactive MFA prompt. Alpacon matches a command against the patterns using these rules:

- **Patterns match the command being elevated, which does not include the `sudo` prefix.** By the time Alpacon evaluates it, the `sudo` you typed is no longer part of the command—so `sudo systemctl restart nginx` is matched as `systemctl restart nginx`. Write patterns without `sudo`: use `apt-get update`, not `sudo apt-get update`. A pattern that contains `sudo` never matches.
- **Matching is full-string.** The entire command must match the entire pattern. `*` is the only wildcard; there is no other glob or regex syntax. A `*` standing alone at the end of a pattern covers all remaining arguments, and any other `*` stays inside one word. If the first word of a pattern contains `*`, including a standalone `*`, it never covers a command line that begins with a shell prefix (`time`, `!`, `if`, `then`, `else`, `elif`, `while`, `until`, `do`, `{`). Such commands need a pattern that spells the prefix literally. Leading `NAME=value` assignments are removed before matching, just like the `sudo` word itself, so sudo patterns must not include them. For example, `sudo DEBIAN_FRONTEND=noninteractive apt-get update` matches `apt-get *`, not `DEBIAN_FRONTEND=noninteractive apt-get update`. A `*` that follows literal text never matches a parent-directory segment (`..` followed by `/`, `:`, `,`, whitespace, or the end of the word), so `--sudo 'rm -rf /tmp/build-*'` does not cover `rm -rf /tmp/build-x/../etc`.
- **Compound commands are split.** Input joined by shell operators (`&&`, `||`, `;`, `&`, pipes) is split into sub-commands, and every sub-command must match at least one pattern. A command containing a redirection (`>`, `<`, `2>&1`, and similar) matches no pattern.
- **Whitespace is normalized; everything else is exact.** Runs of spaces collapse to a single space before matching. Otherwise the match is literal—flags, argument order, and absolute paths all count. `apt-get install -y nginx` does not match `apt-get install nginx`, and `/usr/bin/apt-get update` does not match `apt-get update`.

| Pattern | Matches | Does not match |
|---------|---------|----------------|
| `systemctl restart nginx` | `systemctl restart nginx` (exact); `sudo systemctl restart nginx` (the shell-typed `sudo` is not part of the matched command) | `systemctl restart nginx.service` |
| `systemctl restart *` | `systemctl restart nginx`, `systemctl restart php-fpm` | `systemctl status nginx` |
| `apt-get update` | `apt-get update` | `apt-get update && apt-get upgrade` (unless `apt-get upgrade` is also registered) |
| `tail -f /var/log/nginx/*.log` | `tail -f /var/log/nginx/error.log` | `tail -n 100 /var/log/nginx/error.log` |
| `docker compose *` | `docker compose up -d`, `docker compose ps` | `docker run nginx` |

## Session details

Pass `--use` to set the new session as the workspace's active session, so subsequent `exec`, `websh`, `cp`, and `tunnel` commands attach to it without `--work-session`. When approval is required, combine `--use` with `--wait`—the session is attached once it reaches the **active** state.

If the work needs sudo, pre-declare the command patterns with `--sudo`. This attaches sudo policies where the session approval takes the place of MFA, so a non-interactive caller (e.g. an AI agent running `exec`) can run those exact sudo commands without an interactive MFA prompt. Each `--sudo` value is a comma-separated pattern list forming one policy—literal commas inside a pattern are not supported, so pass the flag again for each policy that needs them. The `sudo` scope is added automatically, and the policies are submitted for approval together with the session. If a sudo command is later denied, add it to the session with [`alpacon work-session update`](/reference/cli/work-session/update/).

When an AI agent drives the CLI, the session is an agent session. The CLI detects Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Cline, and Goose from the environment variables they set in the shells they run, and names the AI agent on every request. For an AI agent the CLI doesn't detect (for example Aider), set `AI_AGENT=<name>` in its environment. An agent session follows the workspace's approval rules. In Advisory mode it starts without waiting for approval. Websh and Kubernetes aren't available to it.

`--requester-type user` is refused while an AI agent is detected. If you are running the command yourself, use a terminal outside the AI agent's environment. Commands an AI agent runs must go through an agent session. `--requester-type agent` opens an agent session without naming an AI agent.

Pass `--account` to name the account the work runs as on the servers (for example `root`), so the approver sees it with the request. On Windows servers the account is an audit label and commands run as SYSTEM; see [permissions on Windows](/reference/platforms/windows/#permissions-and-identity-on-windows).

Source: https://docs.alpacax.com/reference/cli/work-session/create/
