Work sessions reach the CLI: making bash scripts session-aware

Your bash script doesn't know it's a privileged session. Your runbook doesn't either. Here's what changes when the CLI itself becomes session-aware.

If you've ever run a production change from a terminal, you've probably written something like this at the top of a remediation script:

#!/usr/bin/env bash
# Production change: ticket INC-2384
# Approved verbally in #incidents by @oncall-lead
# Scope: restart auth-svc on prod-api-{01..04}

That comment is the closest thing to "declared intent" that most shops have. The audit log captures every command the script runs, but it doesn't know why you ran them, who approved them, or where the change starts and stops. When the auditor asks "show me what changed in production last Thursday," you stitch four log sources together the night before the review.

Alpacon's W19 release made the work session a first-class object across the server, web console, and agent—a single named container with declared purpose, an approval gate, a unified timeline, and a post-session summary. The remaining gap was the CLI: the surface where SREs, runbooks, and automation actually live.

With alpacon-cli v1.4.6, that gap closed.

What shipped

alpacon-cli v1.4.6 adds:

• A top-level work-session command tree (PR 165)
• A --work-session flag on exec, websh, cp, and tunnel, plus work-session use to set the active session for the current workspace (PR 167)
• work-session approve, reject, and revoke subcommands (PR 171)

alpacon-web 1.3.15 adds the matching server-side knob: a sudo policy setting that lets operators say "inside an approved work session, skip MFA on sudo" (PR 1150).

If you've read the W19 work-session blog post, the model is the same—declared intent, approval gate, session-scoped sudo, unified timeline, AI summary. This piece is about reaching that model from the terminal.

The CLI flow

Here's an SRE responding to a paging alert on a 200-server fleet. The runbook needs to restart auth-svc on four hosts. Before today, this was a bash one-liner with a comment block. Now it's a session.

1. Open the session with declared purpose.

alpacon work-session create \
  --purpose "INC-2384: restart auth-svc on prod-api-01..04" \
  --scope command \
  --server prod-api-01,prod-api-02,prod-api-03,prod-api-04 \
  --expires-in 2h \
  --wait

The session is created in a pending state with the purpose recorded as a first-class field. --scope declares the access types you need (command, websh, cp, tunnel); --server names the targets; --expires-in (or --expires-at for an absolute RFC3339 timestamp) bounds the window. --wait polls every 10 seconds for up to 30 attempts and returns when the session is approved or rejected, so the requester's terminal blocks here instead of context-switching.

No "approved verbally in #incidents"—the declared intent is the artifact.

2. The approver reviews and approves.

In the realistic on-call flow, the approver is a second engineer on the bridge. They can approve from the web console (where the work-sessions list page now has a filter bar—PR 1150) or from their own CLI:

alpacon work-session approve <session-id>

# Optionally narrow scope or targets at approval time:
alpacon work-session approve <session-id> \
  --scope command \
  --server prod-api-01,prod-api-02

reject <session-id> and revoke <session-id> are the parallel verbs—reject before activation, revoke to force-terminate an approved or active session. All three are superuser-only and the permission check is enforced server-side.

3. Activate the session, pin it for this workspace, then run the change.

alpacon work-session activate <session-id>
alpacon work-session use <session-id>

alpacon exec prod-api-01 -- systemctl restart auth-svc
alpacon exec prod-api-02 -- systemctl restart auth-svc
alpacon exec prod-api-03 -- systemctl restart auth-svc
alpacon exec prod-api-04 -- systemctl restart auth-svc

activate flips the session from approved to active. use writes the active session ID into ~/.alpacon/config.json for the current workspace, so every subsequent exec, websh, cp, and tunnel call attaches the session automatically. Each tagged call prints Using work-session <uuid> to stderr so --output json pipelines stay clean.

Three ways to attach a session, in resolution order:

# 1. Inline flag — overrides everything else, single invocation
alpacon cp ./hotfix.tar.gz prod-api-01:/tmp/ --work-session <session-id>

# 2. Env var — shell-scoped, overrides workspace config, ideal for CI runners
export ALPACON_WORK_SESSION=<session-id>
alpacon exec prod-api-01 -- systemctl restart auth-svc

# 3. Workspace config via 'work-session use' — sticks until you unset it
alpacon work-session use <session-id>
# To clear:
alpacon work-session use --unset
# To inspect:
alpacon work-session current

Resolution priority: --work-session flag > ALPACON_WORK_SESSION env var > workspace config > no session.

4. Complete the session when the change is done.

alpacon work-session complete <session-id>

The session ends, the in-session policy stops applying, and the unified timeline is now exportable as a single audit artifact—the same one the W19 blog post described for human shell sessions, but driven entirely from a terminal. If you need more time mid-flight, alpacon work-session extend <session-id> --expires-in 1h pushes the expiry back.

The MFA-bypass policy

The matching alpacon-web 1.3.15 setting deserves its own paragraph because it's the operator-facing knob that makes session-scoped intent practical for automation.

Per-command MFA prompts are the right default for ad-hoc privileged work. They are not the right default inside an approved session where the purpose, scope, and approver are already on file—automation will get blocked, on-call engineers will start working around the prompts, and you'll end up with a worse audit trail, not a better one.

The new sudo policy setting (PR 1150) lets a workspace admin say: "inside a work session that's been approved for this scope, the declared purpose and approver substitute for a per-command MFA prompt." Outside that session, MFA still fires. The governance signal moves up a level—from "did this command prompt MFA?" to "did this session have declared intent and an approver?"—without losing it.

What this completes

Session-scoped intent is one of the moat pillars Alpacon has been building toward all year. With this release, it's end-to-end across server → console → agent → CLI. The CLI was the last surface where session governance was bypassable; a script could alpacon exec its way through a privileged change and the audit log would capture the commands but not the session boundary. That gap is now closed.

For an SRE running automated remediation, this is the difference between "we have audit logs" and "we have an audit unit." The session is the artifact your auditor asks for—declared purpose, approver, timeline, summary, scope—and your runbook produces it as a side effect of doing the work.

For a CISO in a SOC 2 or HIPAA cycle, the question shifts from "can you reconstruct what happened?" to "show me the session." One screen, one URL, exportable. Including the ones that ran from a terminal.

If you want the longer "why session-scoped intent is the moat" argument, the W19 post is the canonical reference: the W19 work-sessions post. If you want to try the CLI flow, alpacon-cli v1.4.6 is on GitHub (release notes) and the docs are at docs.alpacax.com.