Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
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

1
Open the Runbooks view to see platform (system-managed) and project runbooks.
2
Pick a published runbook, fill in any parameters, and provide a reason if the target environment is production.
3
Run it; output and exit status are returned, and production/required runs are recorded.
4
For ad-hoc work, use one-off commands from the workspace (subject to policy).

​
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

Runbooks and commands execute against the active target with the right guardrails applied.

​
Common failures

  • 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.

Production safeguards and approvals

How a target’s environment is classified, why production access is gated, and the reason/approval flow members must follow.

Access and permissions

How terminal permissions are derived from team role, project ownership, per-user grants, and platform admin, and what each permission unlocks.

Terminal policy and file transfer

The policy controls owners/admins use to govern terminal behavior, plus browsing and transferring files within a session.