SOC 2 CLI: Run a SOC 2 Program from the Terminal

A SOC 2 CLI gives engineers a terminal interface for the records and work behind a SOC 2 program. A useful command line tool can describe its data model, inspect records and relationships, validate proposed changes, calculate due work and readiness, and prepare audit output. It should also make its write boundary obvious. The tool can check structure and workflow state, but people still provide source facts, approve decisions, operate controls, review evidence, and perform the independent examination.

TL;DR

• Start with read-only discovery. Ask the installed model which record types, fields, relationships, and next actions apply.
• Use model-generated scaffolds and mutation previews instead of composing JSON from memory.
• Use purpose-built commands for recurring obligations, events, approvals, and audit preparation because those operations have lifecycle rules.
• Run validation on every change. Add readiness gates to CI when the program or engagement has reached the stage that the gate measures.
• Review the Git diff before committing. CLI writes should never create a commit on their own.
• Keep control operation and source evidence in the systems that produce them. The CLI manages the connected program record.

What a SOC 2 CLI should do

The AICPA’s Trust Services Criteria are used to evaluate controls relevant to security, availability, processing integrity, confidentiality, and privacy. They do not require a command-line tool. A SOC 2 CLI is an implementation choice for managing the scope, policies, controls, recurring work, evidence records, and audit preparation that support management’s program.

That distinction sets a useful boundary. The CLI should calculate facts that follow from the current records, such as a broken relationship or an overdue obligation. It should not invent a management decision or claim that evidence is sufficient for an examination.

NIST’s Open Security Controls Assessment Language publishes machine-readable XML, JSON, and YAML formats for control-based risk assessment. FileGRC uses OSCAL as an interoperability reference for separating catalogs, requirements, systems, control implementation, assessment plans, and results. That design reference is not a claim of OSCAL compatibility. A compatibility claim would need an explicit import or export path that validates against the supported official schema and documents any lossy mappings.

Map the command surface before you automate it

A CLI becomes safer when operators can tell which commands only read files and which commands write authoritative records or derived output.

Task	Read-only commands	Commands that write
Discover the model	types, guide, model	model migration and generated documentation commands
Inspect records	list, search, get, references, content	create, update, content --write, attach, detach, delete
Plan program work	program-path, workflow, obligations, evidence-map	governed reviews, activations, obligation completions, and event commands
Check readiness	validate, program-readiness, period-health, audit-readiness	none of these checks write program records
Prepare an audit	evidence-packet preview	prepare-audit and evidence-packet generation

Some write commands have a preview mode, but preview does not make the final apply automatic. Review the planned operation, confirm the source facts, apply it through the matching command, and inspect the resulting Git diff.

Start with four discovery commands

Run discovery from the root of the private GRC repository:

npx filegrc program-path --next --json
npx filegrc types --json
npx filegrc guide control --json
npx filegrc list control --workflow --json

Each command answers a separate question. program-path returns the next stage and the work that can move now. types lists the record types installed in the workspace model. guide explains one type, including its fields, relationships, checks, and allowed actions. list --workflow joins the authoritative records with calculated state.

This discovery step keeps scripts and agents tied to the model installed in the repository. A copied example may target an old field or omit a relationship introduced by a later model. The current guide is the contract.

The compliance-as-code guide explains how the model, plain files, Git, and derived state fit together. The CLI is the headless interface to that system.

Inspect one record before changing it

Once you know the record in scope, inspect its mutation shape, inbound references, and valid relationship candidates:

npx filegrc get control CONTROL_ID --mutation
npx filegrc references CONTROL_ID --json
npx filegrc guide control --id CONTROL_ID --json

The mutation view includes the current record, companion content when present, and the revision needed for an update. references shows records that point to the target. The guide stays type-level: it describes checks, allowed relationship targets, and the expected path for the supplied ID. It does not load that record or prove that the ID exists. Use list control --workflow for calculated record state and get for the current record and revision.

Do this even for a small edit. An owner, policy, system, evidence source, or obligation may have changed since the last read. Revision checks stop a stale write instead of silently overwriting newer work.

Create an ordinary record through one validated payload

Start with a scaffold generated from the active model:

set -eu
umask 077
mutation_dir=$(mktemp -d)
trap 'rm -rf "$mutation_dir"' EXIT
npx filegrc scaffold control \
  --title "Quarterly access review" > "$mutation_dir/control.json"

The scaffold is a prompt, not a completed compliance record. Fill it with reviewed organization facts and leave missing facts in a non-final state. Then preview and apply the same payload:

npx filegrc preview-mutation "$mutation_dir/control.json" --json
npx filegrc create "$mutation_dir/control.json" --json
npx filegrc validate --json

Creating a Control does not add it to a Program. Program membership lives in the Program’s controlIds, so link the reviewed Control in a separate mutation:

npx filegrc get program PROGRAM_ID \
  --mutation > "$mutation_dir/program-update.json"
# Add the new Control ID to program-update.json record.controlIds.
npx filegrc preview-mutation "$mutation_dir/program-update.json" --json
npx filegrc update \
  program \
  PROGRAM_ID \
  "$mutation_dir/program-update.json" \
  --json
npx filegrc program-readiness --summary --json

That program change may open an applicability review. Follow the calculated next action rather than treating membership as an applicability conclusion.

For an update, retain the current revision in the payload:

npx filegrc get control CONTROL_ID \
  --mutation > "$mutation_dir/control-update.json"
# Edit only the reviewed fields in the private update file.
npx filegrc preview-mutation "$mutation_dir/control-update.json" --json
npx filegrc update \
  control \
  CONTROL_ID \
  "$mutation_dir/control-update.json" \
  --json
npx filegrc validate --json

The private scratch directory starts with mode 700, the restrictive umask protects each new payload, and the shell trap removes the directory on exit. Avoid pasting private JSON into recorded shell history or a shared terminal. A successful preview proves that the payload matches the model and can show its workflow effect. It does not prove that the facts are true, the control operated, or the evidence is good enough.

Use workflow commands for scheduled and event work

Ordinary CRUD is the wrong interface for a lifecycle operation. FileGRC has two recurring-work paths. An ordinary activity completion records its window, deadline, owner, result, evidence, and review. A rule-based reconciliation can roll up a governed population and its reconciliation conclusion. Start either path with the calculated queue. For an ordinary completion, create the matching scaffold using the private scratch directory from the prior section:

npx filegrc obligations --program PROGRAM_ID --json
npx filegrc complete OBLIGATION_ID \
  --scaffold \
  --window-start 2026-07-01 \
  --program PROGRAM_ID \
  --completed-on 2026-07-10 > "$mutation_dir/completion.json"
# Fill and review the private completion file, then apply it.
npx filegrc complete \
  OBLIGATION_ID \
  "$mutation_dir/completion.json" \
  --json

Fill the private completion file from the owner’s reviewed work before applying it. Use reconcile-obligation, not complete, for a rule-based occurrence when one conclusion governs a full population. Keep one rolled-up occurrence when the same owner, window, population rule, and conclusion apply. Split the work when a member needs its own owner, deadline, conclusion, or follow-up.

Confirmed events need a different command because one event can create a full, model-defined checklist atomically:

npx filegrc trigger person-started \
  --occurred-on 2026-09-01 \
  --program PROGRAM_ID \
  --subject PERSON_ID \
  --title "New team member started" \
  --json

The event type, subject, and occurrence date must come from a person or an authoritative source. Complete the generated Action Items with complete-action, then close the parent event with complete-event after its required work is done. Do not infer that an event occurred from an ambiguous message or a filename.

The recurring compliance tasks guide goes deeper on windows, cutoffs, populations, exceptions, and missed work.

Put validation and stage-specific gates in CI

Run model and reference validation on every proposed change:

npx filegrc validate --json

Readiness checks answer narrower questions. Add the ones that match the stage of the repository or engagement:

(
set -eu
umask 077
ci_output_dir=$(mktemp -d)
trap 'rm -rf "$ci_output_dir"' EXIT
npx filegrc program-readiness \
  --require-ready \
  --summary \
  --json > "$ci_output_dir/program-readiness.json"
npx filegrc period-health \
  AUDIT_ID \
  --require-healthy \
  --json > "$ci_output_dir/period-health.json"
npx filegrc audit-readiness \
  AUDIT_ID \
  --require-ready \
  --json > "$ci_output_dir/audit-readiness.json"
npx filegrc evidence-packet \
  --audit AUDIT_ID \
  --preview \
  --require-ready \
  --json > "$ci_output_dir/evidence-packet.json"
)

These flags return a nonzero exit status when the required condition does not pass, so CI can block a merge. Introduce them at the right time. An early program can be structurally valid while readiness work remains open, and that is useful state rather than a broken repository.

The full JSON can contain program IDs, evidence details, management gaps, and reporting destinations. Keep it in a private temporary directory, publish it only as an access-controlled artifact with suitable retention, and remove it after the job. Show a concise, redacted summary in general build logs. Preserve the record ID, status, reason, and next allowed action in the restricted output so the person fixing the problem can act. A blocked item should name the prerequisite that prevents progress.

Prepare audit output without hiding writes

Audit preparation starts from an explicit Type 1 or Type 2 engagement, its scope, date or period, and management records. The preparation command is a write. It links the engagement to governed documents and may create required population records:

npx filegrc prepare-audit AUDIT_ID --json
git status --short
git add --intent-to-add -- data/
git diff HEAD -- data/

Review that diff, finish any required records, and run filegrc validate. Commit the approved audit-preparation changes through the repository’s normal review process. Packet readiness requires a clean Git revision, so confirm that git status --short returns no output before continuing. When the engagement records pass their management checks, preview the evidence packet without writing packet files:

npx filegrc evidence-packet \
  --audit AUDIT_ID \
  --preview \
  --require-ready \
  --json

Remove --preview only when you intend to write the packet under .filegrc/. The generated packet binds indexes, historical source versions, checksums, and readiness output to the selected engagement. Delivery-ready is a management check. The CPA firm still decides which procedures to perform, which samples to select, and whether the evidence is sufficient and appropriate.

The audit evidence packet guide explains the revision, population, external-reference, and clean-worktree checks behind that output.

Make Git the write review boundary

FileGRC CLI write commands change files but do not create commits. After any write, review the full program diff:

git status --short
git add --intent-to-add -- data/
git diff HEAD -- data/
npx filegrc validate --json

git add --intent-to-add makes new files visible in the diff without staging their contents. Confirm IDs, owners, dates, status changes, relationships, companion Markdown, and evidence references. Reject secrets, credentials, session material, regulated personal data, confidential reports that do not belong in the repository, and personal data that may later need deletion.

Git supplies version-control facts: author, commit time, message, revision, rename history, and diff. Keep domain dates in records. An access review completed on September 3 needs that completion date even when its record lands in Git on September 4.

The SOC 2 in Git guide covers repository access, protected branches, change review, and revision-bound evidence in more detail.

Use the browser and CLI for the same rules

A headless interface should not have a separate data model or a weaker version of the workflow. FileGRC routes browser, HTTP, and CLI operations through the same domain functions and the same { record, content } mutation shape. A direct file edit receives the same validation and derived readiness result as an equivalent browser edit.

Use the browser when a person benefits from forms, relationship pickers, and rendered Markdown. Use the CLI for discovery, scripts, CI, bounded agent work, and reproducible checks. The interface can change while the authoritative files and rules stay the same.

If you start the editable local server, keep its default loopback binding. It has no authentication, so do not bind it to an untrusted network without trusted authentication.

What the CLI does not replace

A SOC 2 command line tool does not run identity, cloud, backup, endpoint, monitoring, incident-detection, training, procurement, or ticketing systems. Those systems operate controls and hold source records. The GRC repository catalogs them as evidence sources and connects fixed artifacts to the program facts they support.

The CLI also does not replace management or the CPA firm. Management defines the service boundary, chooses applicable criteria, designs and operates controls, approves governed content, makes risk decisions, and takes responsibility for its description and assertions. The CPA firm independently plans and performs the examination.

FileGRC gives engineers a local SOC 2 CLI backed by JSON, Markdown, Git, and one model-driven workflow. Start with program-path --next --json, keep the first pass read-only, and add write authority one reviewed operation at a time. For agent operation, use the AI agent for SOC 2 runbook to set explicit read, draft, write, and human decision boundaries.