> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbooks and one-off commands

> Run versioned platform and project runbooks, and execute ad-hoc one-off commands, within the project terminal policy.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Execute curated runbooks (including platform diagnostics) and one-off commands without hitting avoidable validation errors.

## Prerequisites

* terminal.execute\_runbooks for runbooks; a session permission for one-off commands

## Workflow

<Steps>
  <Step>
    Open the Runbooks view to see platform (system-managed) and project runbooks.
  </Step>

  <Step>
    Pick a published runbook, fill in any parameters, and provide a reason if the target environment is production.
  </Step>

  <Step>
    Run it; output and exit status are returned, and production/required runs are recorded.
  </Step>

  <Step>
    For ad-hoc work, use one-off commands from the workspace (subject to policy).
  </Step>
</Steps>

## Runbooks

* Runbooks are published, versioned commands with typed parameters and an eligible-environments list.
* Platform runbooks (e.g. runtime diagnostics) ship system-managed; project runbooks are authored with terminal.manage\_runbooks.
* A runbook can declare required permissions and whether it needs production approval.

## Production runbooks always need a reason

In a production environment, running any runbook requires a reason between 10 and 500 characters — even when the runbook does not require approval. Enter the reason in the runbook card before pressing Run; the Run button stays disabled until the reason is valid. (Approval-required runbooks additionally need an approval for members.)

## One-off commands

* One-off commands must be enabled by the terminal policy and may be restricted to an allowlist.
* Production one-off commands also require a 10–500 character reason.
* Commands run against the active application target and return stdout, stderr, and an exit code.

## Expected result

<Check>
  Runbooks and commands execute against the active target with the right guardrails applied.
</Check>

## Common failures

<Warning>
  * production runbooks require a reason between 10 and 500 characters: provide the reason in the runbook card before Run.
  * runbook is disabled by terminal policy / runbook is not eligible for this environment: enable runbooks or pick an eligible runbook.
  * one-off commands are disabled by terminal policy / command is not allowed by terminal policy: enable commands or use an allowlisted command.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Production safeguards and approvals" href="/terminal/production-safeguards">
    How a target’s environment is classified, why production access is gated, and the reason/approval flow members must follow.
  </Card>

  <Card title="Access and permissions" href="/terminal/access-and-permissions">
    How terminal permissions are derived from team role, project ownership, per-user grants, and platform admin, and what each permission unlocks.
  </Card>

  <Card title="Terminal policy and file transfer" href="/terminal/policy-and-file-transfer">
    The policy controls owners/admins use to govern terminal behavior, plus browsing and transferring files within a session.
  </Card>
</CardGroup>