Context Management

The context command group manages your active system and framework scope. Platform-backed compliance operations (evidence, narratives, issues, monitoring, control status) run inside exactly one system + framework pair at a time.

This works similarly to kubectl config use-context — set your scope once, then run commands within it.

List Available Systems

$ pretorin context list

  [°~°]  Fetching systems...

                    [°◡°]/  Systems & Compliance Status
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ System Name    ┃ Framework ID     ┃ Scale       ┃ Progress % ┃ Status      ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ My Application │ nist-800-53-r5   │ moderate    │        42% │ in_progress │
│ My Application │ fedramp-moderate │ moderate    │        28% │ in_progress │
│ Internal Tool  │ cmmc-l2          │ baseline    │        75% │ implemented │
└────────────────┴──────────────────┴─────────────┴────────────┴─────────────┘

One row is printed per attached framework, so a system with three frameworks appears three times. Scale is the platform’s confirmed scope scale tier (baseline, moderate, or comprehensive) — it is read from the platform, never inferred locally, and shows - until scope is approved. Set the target tier with pretorin scope target-tier. A system with no attached framework shows - for both Framework ID and Progress % with the status no frameworks; a system whose compliance status could not be fetched shows error fetching status rather than being dropped from the listing.

Set Active Context

# Interactive — prompts for system and framework selection
pretorin context set

# Explicit
pretorin context set --system "My Application" --framework nist-800-53-r5

# Skip automatic source verification after setting context
pretorin context set --system "My Application" --framework nist-800-53-r5 --no-verify

Pretorin stores the canonical system ID for stability and also caches the last known system name for display. After setting context, source verification runs automatically unless --no-verify is passed. If you change API keys or platform endpoints with pretorin login, the stored active context is cleared automatically so old scope does not leak into the new environment.

Show Current Context

$ pretorin context show
╭──────────────────────── Active Context ─────────────────────────╮
│ System: My Application (sys-1234...)                           │
│ Framework: nist-800-53-r5                                      │
│ Progress: 42%                                                  │
│ Status: in_progress                                            │
╰─────────────────────────────────────────────────────────────────╯

# Compact summary for shell use
pretorin context show --quiet

# Fail fast if the stored context is missing, stale, or cannot be verified
pretorin context show --quiet --check

context show validates the stored system and framework against the platform when credentials are available. If the system has been deleted or the framework is no longer attached, the command reports that state explicitly instead of silently showing a stale context.

When validation does not come back clean, the panel gains Validation and Note lines carrying the reason, and its border turns amber. --check exits non-zero for every one of those states, not only a deleted system or a detached framework:

• no context is stored at all;
• the session is not logged in, so the stored context can only be echoed back unverified;
• the platform could not be reached to validate the system or its frameworks;
• the context was set against a different endpoint than the one now in effect. Pretorin records the platform URL alongside the context and refuses to validate across a mismatch, so exporting PRETORIN_PLATFORM_API_BASE_URL without re-running pretorin context set lands here (see Authentication).

Verify Context

Verify the active context against source attestation:

# Full output
pretorin context verify

# Compact output with custom TTL
pretorin context verify --ttl 7200 --quiet

Source Manifest

Show the resolved source manifest and evaluate it against detected sources:

pretorin context manifest
pretorin context manifest --quiet

Clear Context

pretorin context clear

JSON Output

Every context subcommand honours the global --json flag, which comes before the subcommand:

pretorin --json context show
pretorin --json context list

--json context show is the scripting surface to prefer over --quiet: it returns the full payload, including validation_state (valid, invalid, or unverified) and validation_error, so a script can tell a deleted system apart from an endpoint it simply could not reach. --json context list returns one object per row with system_name, system_id, framework_id, cached_scale_tier, progress, and status.

Single-Scope Enforcement

All platform write operations must target exactly one system + framework pair. This includes:

• Evidence creation and push
• Narrative updates
• Control issues
• Monitoring events
• Control status updates

If you need to work across multiple frameworks (e.g., fedramp-low and fedramp-moderate), run them as separate operations:

# Work on FedRAMP Moderate
pretorin context set --system "My App" --framework fedramp-moderate
pretorin evidence push

# Switch to FedRAMP Low
pretorin context set --system "My App" --framework fedramp-low
pretorin evidence push

Some commands also accept explicit --system and --framework flags, which override the stored context for that invocation.