CLI Reference

The ssg binary is the primary interface for SigmaShake governance.

Commands

ssg auth

Manage authentication. Required before most ssg commands work.

ssg auth login              # Interactive login — browser opens accounts.sigmashake.com
ssg auth login --sso        # Enterprise SSO (OIDC or SAML 2.0)
ssg auth login --token=KEY  # Authenticate with an API key
ssg auth status             # Show current auth state
ssg auth logout             # Clear stored credentials
ssg auth refresh            # Re-fetch license after subscription change

Headless / Docker / Kubernetes: set SSG_API_KEY=ssg_pat_… (mint at accounts.sigmashake.com/settings/tokens) instead of running ssg auth login. The CLI exchanges the token for a 30-day (Pro) or 90-day (Enterprise) license JWT on first invocation. See Kubernetes for a full deployment example with Secret, PVC-backed JWT cache, and token rotation guidance.

Default flow (recommended): Running ssg auth login in a TTY shows a menu. Select Browser (recommended) — your browser opens to accounts.sigmashake.com. If you have an active session (GitHub, Google, or corporate SSO), just click Authorize ssg CLI. Done.

SSO flags (for --sso — enterprise IdP login without a browser session):

Flag	Description
`--issuer=URL`	IdP issuer/discovery URL
`--client-id=ID`	OAuth / SP client ID
`--protocol=oidc\|saml`	Protocol (default: `oidc`)

SSO can also be configured via environment variables (SSG_SSO_ISSUER, SSG_SSO_CLIENT_ID) or fleet configuration (~/.sigmashake/fleet.toml).

Credentials are stored in ~/.sigmashake/hosts.toml.

ssg eval

Evaluate a tool call from stdin JSON.

echo '{"tool":"Bash","input":{"command":"rm -rf /"}}' | ssg eval

Input format:

{
  "tool": "Bash",
  "input": {
    "command": "rm -rf /"
  }
}

Output format (stdout, JSON only):

{
  "decision": "block",
  "rule_id": "no-destructive-ops",
  "reason": "Destructive command blocked.",
  "duration_ms": 1
}

Flags:

--rules <dir> — Use rules from a specific directory (default: .sigmashake/rules)
--explain — Include matched condition details in output

ssg serve

Start the governance dashboard (also auto-starts the eval daemon).

ssg serve
ssg serve --port 8080

Default port: 5599. Auth is off by default. Enable with --auth to require a token — the URL with token is displayed on startup. You can also set SSG_DASHBOARD_TOKEN=<value> env var to force a specific token.

ssg serve automatically co-starts the eval daemon (ssg daemon) if it isn't already running. Both are stopped together on Ctrl+C / SIGTERM.

Dashboard features:

Real-time audit log with SSE updates
Pending approval queue for ASK decisions
Rule viewer and editor
Performance metrics and profiling

ssg daemon

Start the persistent eval daemon. The hook connects to it via Unix socket for ~5ms eval latency (vs ~115ms process spawn).

ssg daemon           # Start daemon (auto-exits after 30min idle)
ssg daemon --status  # Check if daemon is running
ssg daemon --stop    # Stop the running daemon

The daemon is auto-started by the hook on first invocation and by ssg serve on dashboard startup. Rules are hot-reloaded on file change and every 5 minutes. Socket path: ~/.sigmashake/evald.sock.

ssg keys

Manage Ed25519 signing keys for content integrity verification.

ssg keys generate    # Create a new key pair (~/.sigmashake/keys/)
ssg keys show        # Display public key (hex-encoded)
ssg keys register    # Upload public key to hub.sigmashake.com (requires auth)
ssg keys sign        # Sign content from stdin, output hex signature
ssg keys verify      # Verify content+signature+pubkey from stdin

Key files:

Private key: ~/.sigmashake/keys/signing.key (mode 0600)
Public key: ~/.sigmashake/keys/signing.pub (mode 0644)

First-time setup:

ssg keys generate    # create key pair
ssg auth login       # authenticate with GitHub
ssg keys register    # upload public key to the hub

Once registered, all rulesets you publish will include an Ed25519 signature that consumers can verify.

ssg check

Scan files for rule violations.

ssg check .
ssg check src/

ssg lint

Validate .rules file syntax and native engine compatibility.

ssg lint

Checks for:

Parse errors (malformed rules)
Unknown fields or operators
Invalid regex patterns
Missing required fields (PROMPT for ASK, SUBSTITUTE for FORCE)

Also emits warnings (not errors) for rules that fall back to the TypeScript evaluator instead of running in the native Zig engine:

Custom input fields (input.xxx) not supported natively
More than 16 condition groups per rule
More than 8 conditions per group
Regex patterns exceeding 500 characters

Rules with warnings still work correctly — the TypeScript fallback handles them. The warning tells you which rules won't benefit from native-engine speed.

25 file(s) valid, 0 errors, 3 warning(s) — 108/109 rule(s) native-compatible

ssg format

Format .rules files — normalize whitespace, keyword casing, field order, and split oversized rules.

ssg format           # rewrite files in-place (default)
ssg format --check   # exit 1 if any file needs reformatting (CI)
ssg format --diff    # print unified diff, no writes

Transformations applied (in order):

Split rules with more than 16 OR groups into rule-id-part-1, rule-id-part-2, etc. (all metadata copied to every part)
Normalize indentation to 2 spaces
Canonical keyword casing (DENY, ALLOW, LOG, SHADOW, ASK, FORCE, IF, OR, AND, MESSAGE uppercase)
Canonical field order: priority → severity → decision target → [SUBSTITUTE] → IF/OR groups → MESSAGE → [PROMPT] → [RUN] → [WEBHOOK]

Hard errors: If any rule group has more than 8 AND conditions, format aborts with no writes. AND groups cannot be split automatically — reduce conditions manually.

Safety: In-place mode writes to a temp file, verifies the output parses correctly, then atomically renames. Running twice produces no changes (fully idempotent).

Use --check as a CI gate to ensure committed .rules files are always in canonical form.

ssg setup

Interactive setup wizard. Guides through client selection, config values, hub ruleset search, and rule enable/disable. Safe to re-run at any time for reconfiguration.

ssg setup    # interactive 4-step wizard (requires a TTY)

Wizard steps:

AI client — confirm or override auto-detected client
Config — dashboard port, ask timeout, fallback (block/ask/allow), verbose
Hub search — live search of hub.sigmashake.com; browse featured rulesets or type a query
Rule toggle — checkbox list to enable/disable individual rules from each selected ruleset

ssg init

Non-interactive initialization for CI/scripted use.

ssg init                         # install only adapters whose client is detected
ssg init --client claude-code    # force a specific adapter
ssg init --client all            # install every non-generic adapter
ssg init --global                # write permissions to ~/.claude/settings.json (all projects)
ssg init --list                  # list available adapters

Creates .sigmashake/rules/ with a starter ruleset, installs the PreToolUse hook, and auto-configures permissions.allow and permissions.deny in .claude/settings.json so Claude Code tools work out of the box.

Use --global to write permissions to ~/.claude/settings.json once for all projects instead of per-project.

ssg new

Scaffold a new .rules file from flags (non-interactive).

ssg new --name block-secrets --decision DENY --target read
ssg new --name audit-writes --decision LOG --target write

Flags:

Flag	Description	Default
`--name=<id>`	Rule identifier	Required
`--decision=<d>`	DENY, ALLOW, LOG, SHADOW, ASK, FORCE	DENY
`--target=<t>`	execution, read, write, search, agent, network, any	any
`--severity=<s>`	error, warning, info	error
`--priority=<n>`	Priority number (higher = evaluated first)	100

Writes to .sigmashake/rules/<name>.rules.

ssg status

Check system health.

ssg status

Output:

{
  "healthy": true,
  "rules": 22,
  "pending": 0,
  "dashboard": "running"
}

ssg doctor

Run a comprehensive health check across all SSG subsystems. The most complete diagnostic available — paste --json output into support tickets.

ssg doctor               # colored health report with fix suggestions
ssg doctor --json        # machine-readable JSON (ideal for support tickets and CI)

Example output:

ssg doctor  v0.14.6

  ✓ Version              ssg v0.14.6 on linux/x64 (Bun 1.3.11)
  ✓ Rules (local)        28 .rules files in /project/.sigmashake/rules
  ✓ Rules (global)       27 .rules files in ~/.sigmashake/rules
  ✓ SQLite DB            126 rules in ~/.sigmashake/rules.db
  ✓ Daemon               PID 12345, socket active
  ✓ Dashboard            PID 67890 → http://localhost:5599
  ✓ Adapter: claude-code Detected & healthy
  – Adapter: cursor      Not detected
  – Adapter: codex       Not detected
  ✓ Native Engine        Loaded — sub-ms eval available
  ✓ License              PRO plan
  ✓ Hub connectivity     hub.sigmashake.com reachable (200)
  ✓ Hub rulesets         3 installed (hub-pins.json)

  10 ok, 0 warnings, 0 failures, 2 skipped

Checks performed:

Check	What it verifies
Version	SSG version, OS platform, Bun runtime
Rules (local)	`.rules` files in project `.sigmashake/rules/`
Rules (global)	`.rules` files in `~/.sigmashake/rules/`
SQLite DB	Rule count in local `~/.sigmashake/rules.db`
Daemon	`evald` PID and socket liveliness
Dashboard	`ssg serve` process status
Adapter: `<name>`	Detection and health of each AI client adapter
Native Engine	Zig+Rust FFI eval engine availability
License	Plan tier (unlicensed / pro / enterprise)
Hub connectivity	Network reachability of `hub.sigmashake.com`
Hub rulesets	Installed rulesets in `~/.sigmashake/hub-pins.json`

Status codes:

✓ ok — check passed
⚠ warn — degraded but functional (fix hint shown in cyan)
✗ fail — critical failure → exit code 1
– skip — not applicable in this environment

Exit codes: 0 if all checks are ok/warn/skip. 1 if any check fails.

Auth: ssg doctor is auth-exempt — it works before login so you can diagnose auth problems.

ssg list

Show all loaded rules.

ssg list
ssg list --json

ssg rule

Non-interactive rule management for AI agents and scripts. All output is JSON. No interactive prompts. Auth-exempt — works without GitHub login in agent contexts.

ssg rule list [--json]                   # List all rules with file, status, decision
ssg rule disable <id>                    # Disable a rule by ID
ssg rule enable <id>                     # Enable a rule by ID
ssg rule set-decision <id> <decision>    # Change rule decision type (block, ask, log, allow, force)
ssg rule search <query> [--json]         # Search rules by ID or message keyword

Exit codes: 0 = success, 1 = rule not found / invalid argument, 2 = parse error.

ssg sync

Pull rules from edge API to local SQLite.

ssg sync

ssg push

Push local .rules files to edge API.

ssg push
ssg push --kind=workflows           # Hub v2 — publish a workflow pack
ssg push --kind=prompts             # Hub v2 — publish a prompts pack

Flag	Default	Notes
`--kind=<k>`	`rules`	Pack kind. One of `rules \| prompts \| profiles \| workflows \| memory`. Set at create; immutable on republish.
`--private`	off	Push to a private org ruleset. Requires `--org` + `--name`.

ssg test-rule

Test a specific rule against a tool call.

echo '{"tool":"Bash","input":{"command":"rm -rf /"}}' | ssg test-rule --rule no-destructive-ops --explain

ssg metrics

Show session metrics.

ssg metrics

ssg blocked

Show recently blocked commands.

ssg blocked
ssg blocked --since 1h

ssg dedupe

Detect duplicate or overlapping rules.

ssg dedupe

ssg flight

View flight recorder telemetry.

ssg flight

ssg profile

Profile evaluation latency.

ssg profile
ssg profile --last=100   # analyze last 100 evals
ssg profile --ai         # emit JSON for AI triage

ssg usage

Show eval usage, storage, and plan limits.

ssg usage
ssg usage --json

Displays current eval count, storage utilization, and rate limits for your account.

ssg cost

Per-tool, per-capability, per-decision cost attribution for AI agent activity. Reads from the local cost_ledger table populated by the audit worker on every eval — no network call, no auth required.

ssg cost summary                              # totals by tool, last 7d (default)
ssg cost summary --by=client                  # group by AI client (claude-code, codex, ...)
ssg cost summary --by=capability              # group by capability (execute, read, write, ...)
ssg cost summary --by=decision                # group by decision (allow, block, ask, ...)
ssg cost summary --since=30d                  # widen the window
ssg cost summary --json                       # machine-readable output

Dimensions (--by): tool (default) · client · capability · decision.

Window (--since): accepts <N>d (e.g. 7d, 30d) or a bare integer treated as days. Defaults to 7 days.

Cost rows are recorded by every eval — token counts come from the adapter capability metadata and USD is computed against the active model's per-token rate. If you see "no cost rows yet", run a few evals first or check that the daemon is up (ssg daemon --status).

ssg publish

Publish local .rules files to GitHub and submit to the SigmaShake Rules Hub.

ssg publish

Prerequisites:

GitHub CLI (gh) installed and authenticated (gh auth login)
.rules files in .sigmashake/rules/ (create with ssg init)

Flags:

Flag	Description	Default
`--repo=<name>`	GitHub repo name	`rules-<cwd>`
`--desc=<text>`	Repository description	Auto-generated
`--path=<dir>`	Rules directory to push	`.sigmashake/rules`
`--no-browser`	Print hub URL, don't open browser	false

What it does:

Checks gh auth — exits with instructions if not logged in
Creates github.com/<you>/<repo> (public, idempotent — skips if exists)
Copies .rules files into the repo and pushes to main
Opens hub.sigmashake.com/submit pre-filled with the repo URL

Example:

ssg publish --repo=my-typescript-rules --desc="TypeScript safety rules"
# → Creates github.com/alice/my-typescript-rules
# → Pushes 3 .rules files
# → Opens hub.sigmashake.com/submit in browser

After the browser opens, sign in with GitHub and click Submit to complete.

See Publishing Guide for the full flow including MCP and REST API paths.

ssg hub pull

Install a ruleset from hub.sigmashake.com by UUID. Verifies SHA-256 content hash, TOFU pin, and Ed25519 cryptographic signature before writing rules to disk. Unsigned rulesets are hard-blocked.

ssg hub pull <ruleset-id>

Example:

ssg hub pull 550e8400-e29b-41d4-a716-446655440000
# Fetching ruleset 550e8400...
#   TypeScript v3 by @sigmashakeinc — 12 rules
# Verifying integrity... OK (sha256:4a9f3c1b8e2d7f05...)
# Verifying Ed25519 signature... OK (signed by @sigmashakeinc)
#
# Installed: TypeScript v3
#   Integrity: sha256:4a9f3c1b8e2d7f05... VERIFIED
#   Technologies: ts
#   Files written:
#     .sigmashake/rules/ts.rules

Flags:

Flag	Description	Default
`--path=<dir>`	Directory to write `.rules` files	`.sigmashake/rules`

What it does:

Fetches ruleset metadata and all rule bodies from hub.sigmashake.com/api/rulesets/<id>
Recomputes the SHA-256 content hash from the downloaded rule bodies
Compares the computed hash to the hub-stored content_hash — aborts if they differ
Writes one .rules file per technology to the rules directory
Registers the download on the hub (best-effort, non-fatal)

Getting the ruleset ID: Find it in the URL when viewing a ruleset on the hub: hub.sigmashake.com/ruleset/<id>.

After installing:

ssg sync          # load new rules into the engine
ssg list          # verify rules are loaded

See Security & Trust for details on the integrity verification model.

ssg hub search

Search for packs on the Hub.

ssg hub search <query>                       # search by keyword or technology
ssg hub search typescript                    # find TypeScript rulesets
ssg hub search "git safety" --kind=workflows # Hub v2 — filter by pack kind
ssg hub search agent --kind=memory           # Hub v2 — find memory packs

Flag	Default	Notes
`--kind=<k>`	(any)	Filter to one pack kind. One of `rules \| prompts \| profiles \| workflows \| memory`. Unknown values are silently dropped to avoid typo-driven empty results.

ssg hub update

Check installed rulesets for newer versions.

ssg hub update                  # show available updates
ssg hub update --apply          # automatically pull all updates

ssg hub audit

Verify the transparency log chain integrity for a ruleset. Fetches the full merkle-chained audit history and re-verifies each entry hash locally. Reports the first broken link if tampered.

ssg hub audit <ruleset-id>

Example output (healthy chain):

Fetching transparency log for rules-typescript...

Transparency audit: rules-typescript
  Chain length: 5 entries
  First entry:  2026-04-10 (publish by @sigmashakeinc)
  Last entry:   2026-04-15 (update by @sigmashakeinc)
  Verifying chain locally... VALID
  Chain integrity: VALID ✓

Example output (tampered chain):

  Verifying chain locally... BROKEN

  Chain integrity: BROKEN at entry #3
    Expected: sha256:abc1234...
    Got:      sha256:def5678...

  WARNING: This ruleset's transparency log has been tampered with.
  Report to security@sigmashake.com

The transparency log is also queryable via the Hub API:

GET /api/rulesets/:id/transparency — full chain with verification status
GET /api/transparency/verify?ruleset_id=<id> — server-side chain verification

ssg install <github-url>

Install .rules files directly from a GitHub repository — public or private. No hub account required.

ssg install github.com/my-org/my-rules             # HEAD of default branch
ssg install github.com/my-org/my-rules@main        # explicit branch
ssg install github.com/my-org/my-rules@v1.2.0      # tag
ssg install github.com/my-org/my-rules@abc1234     # commit SHA

Flags:

Flag	Default	Description
`--ref=<branch\|tag\|sha>`	`HEAD`	Git ref to install from
`--dir=<path>`	`.sigmashake/rules`	Path inside the repo where `.rules` files live
`--force`	`false`	Reinstall even if already installed at the same SHA

Requirements for private repos: ssg auth login with the repo OAuth scope. Run ssg auth refresh if you originally logged in before this scope was required.

After installation the commit SHA is recorded in .sigmashake/sources.json so ssg update can detect upstream changes.

See Installing from a Private GitHub Repo for the full walkthrough.

ssg orgs

Manage hub organizations and team-private rulesets. Pro/Enterprise required.

# Organization management
ssg orgs list                                           # list your organizations
ssg orgs create <slug> --name="Display Name"           # create a new org
ssg orgs members <slug>                                 # list members
ssg orgs invite <slug> <github-login> --role=member    # invite a member
ssg orgs remove <slug> <github-login>                  # remove a member

# Private rulesets
ssg orgs rulesets <slug>                               # list org rulesets (public + private)
ssg push --private --org <slug> --name <ruleset-name>  # publish a private ruleset

# Audit + export
ssg orgs audit <slug> --limit=100                      # org management audit log
ssg orgs export <slug>                                 # request data export (owners only)

Roles:

Role	Pull private	Push private	Invite	Manage org
viewer	✓	—	—	—
member	✓	✓	—	—
admin	✓	✓	✓	—
owner	✓	✓	✓	✓

See Organizations & Private Rulesets for the full guide.

ssg certify

Run scenario files through the governance engine to verify rule correctness for Claude Code.

ssg certify                              # run .sigmashake/scenarios/
ssg certify --dir=path/to/scenarios     # custom scenario directory
ssg certify --verbose                    # show per-step detail
ssg certify --json                       # emit JSON report to stdout
ssg certify --rules-dir=path/to/rules   # override rules directory

Scenarios use Claude Code wire format (tool_name, tool_input) and assert expected_decision per step. Exit code 0 if all pass, 1 if any fail.

See Certification for the scenario file format and Hub badge submission.

ssg suggest

Generate governance rules for uncovered tool calls using AI analysis.

ssg suggest                 # analyze recent evals, suggest new rules
ssg suggest --write         # save generated .rules files to disk
ssg suggest --last=100      # analyze last 100 evals (default)
ssg suggest --json          # machine-readable output

Analyzes your audit log for tool calls that weren't matched by any existing rule and proposes new .rules DSL for common unguarded patterns.

ssg insights

Analyze Claude Code conversation history to detect behavioral patterns and surface governance opportunities. No API key required — pattern detection runs entirely locally.

ssg insights                                  # analyze current project
ssg insights --project=/path/to/project       # target a specific project
ssg insights --last=7d                        # only last 7 days
ssg insights --last=24h --category=security   # security signals in last 24h
ssg insights --json                           # machine-readable output
ssg insights --write                          # save report to .sigmashake/insights.json

Categories detected:

Category	Description
`loop`	Same tool called 3+ times consecutively with identical input
`error-spiral`	Tool producing 3+ consecutive errors
`approval-fatigue`	Session where most user responses were very short (over-prompting)
`security`	Access to `.env`, secrets dirs, or unusual network domains
`hotspot`	One capability dominating >50% of all tool calls
`time-sink`	Sessions with very high token/tool-call ratios

Usage with Claude Code:

Run /insights in a Claude Code session — the skill reads ssg insights --json output and synthesizes .rules DSL in-context using your existing subscription. No separate API key needed.

ssg debug

AI-native realtime debugger. Every surface (CLI, MCP, /debug dashboard) reads from the same ssg://<source>/<path> URI resolver so Claude, you, and the daemon see identical data. The RCA oracle pre-computes structured root-cause packs — Claude can read a diagnosis before emitting any response tokens.

# One-shot URI fetch
ssg debug snapshot ssg://daemon/state --json
ssg debug snapshot ssg://audit/recent?limit=20 --json

# Current pre-computed root-cause pack (markdown by default, or --json)
ssg debug rca --current
ssg debug rca --trace=<trace_id> --json

# Long-poll any URI; one JSON envelope per hash change
ssg debug watch ssg://daemon/metrics --interval=500
ssg debug watch ssg://rca/current | tee -a rca.jsonl

# Stream new DebugFrames as JSONL (pair with `run_in_background`)
ssg debug follow --tool=Bash
ssg debug follow --trace=<trace_id>
ssg debug follow --rule=<rule_id>

URI surface:

URI	Description
`ssg://daemon/state`	Daemon runtime snapshot (rules loaded, queues, pending frames)
`ssg://daemon/metrics`	Latency percentiles + decision counters
`ssg://audit/recent?limit=N`	Last N audit rows
`ssg://audit/<audit_id>`	Single audit row with joined trace frames
`ssg://frames/recent?limit=N`	Newest DebugFrames across all traces
`ssg://frames/<trace_id>`	All frames for one eval
`ssg://rules/list?filter=…`	Loaded rules
`ssg://rca/current`	Current top RCA pack
`ssg://rca/<trace_id>`	RCA pack for a specific failed trace
`ssg://native/stats`	Native span buffer stats (Phase C scaffold)

Delta protocol: add --since=<hash> to any snapshot/watch call. The resolver returns {unchanged: true, snapshot_hash: <hash>} when the content hash matches, so a long-poll costs one hash compare instead of re-serializing the full response.

Stale preservation: if the daemon fails to answer mid-fetch, the resolver serves the last cached envelope with stale: true, age_ms: <ms> (up to 30 s). Dashboard, CLI, and MCP all honour this so transient daemon restarts don't break an active debug session.

Frame emission gate: DebugFrames are only emitted when SSG_DEBUG_ENABLED=1 is set on the daemon — zero-cost when disabled. The realtime UI lives at /debug in the dashboard; pre-computed RCA packs auto-load when severity ≥ high.

Usage with Claude Code: run /rca in-session to inject the current pack, or let the /prelude skill opportunistically include it at session start. Via MCP, the ssg_debug_rca, ssg_debug_snapshot, ssg_debug_watch, and ssg_debug_replay tools expose the same URIs.

ssg memory

Persistent agent memory layer — file-backed key/value store partitioned by project + agent identity. Used by Claude Code skills and the MCP server (ssg_memory_get / ssg_memory_put) to carry context across sessions.

ssg memory list                                       # list entries for the current project
ssg memory list --type=feedback                       # filter by type
ssg memory list --project=<id> --agent=<id>           # explicit project/agent scope
ssg memory put --name=<n> --type=<t> --body="..."     # create or update
ssg memory put --name=<n> --type=<t> --body="..." --description="<d>" --id=<id>
ssg memory get <id>                                   # show one entry
ssg memory search <query>                             # substring search across name/body
ssg memory search <query> --type=user --limit=10
ssg memory delete <id>                                # remove one entry

Memory types (--type): user · feedback · project · reference.

Storage: ~/.sigmashake/memory/<project_id>/<agent_id>/<id>.md — one Markdown file per entry, frontmatter holds metadata. Project id is derived from the current working directory when --project is omitted; agent id defaults to the detected client (e.g. claude-code).

JSON mode: every subcommand accepts --json for machine-readable output — recommended for scripts and MCP integrations.

ssg workflow

Declarative multi-gate orchestration for agent workflows. A .workflow file defines an ordered set of gates (shell commands or internal ssg eval invocations); gates run in topological order and a failing gate stops the run unless its on_fail is warn.

ssg workflow list                              # list .workflow files
ssg workflow validate <name>                   # parse + validate without running
ssg workflow run <name>                        # execute gates in order
ssg workflow run <name> --trigger=cli          # tag the run's origin (default: cli)
ssg workflow status                            # recent runs (latest 20)
ssg workflow status --id=<run-id>              # detail for a single run
ssg workflow status --limit=100 --json         # machine-readable output
ssg workflow new <name>                        # scaffold a starter .workflow file

File location: .sigmashake/workflows/<name>.workflow (TOML).

Format:

name = "ship-pr"
description = "Lint -> test -> review -> push"

[[gate]]
id = "lint"
must_pass = "bun run lint"
on_fail = "deny"

[[gate]]
id = "test"
must_pass = "bun test"
depends_on = ["lint"]
timeout_seconds = 300

[[gate]]
id = "review"
must_pass_eval = "ssg policy trace --tool=Edit"
depends_on = ["test"]

Each gate declares exactly one of must_pass (shell command — pass iff exit code 0) or must_pass_eval (internal ssg eval invocation). on_fail is deny | ask | warn (default deny). depends_on must reference other gate ids and cannot form cycles. timeout_seconds defaults to 300 and is clamped to [1, 3600].

Exit codes: 0 passed · 1 failed/aborted · 2 usage/parse error · 3 paused (a gate with on_fail = "ask" stopped the run).

Runs are persisted to the local SQLite database. Use ssg workflow status to inspect gate-level stdout/stderr and timings, or query them programmatically via the GET /api/json/workflows endpoint.

ssg productivity

Composite agent productivity score (0–100) derived from audit-log telemetry. Read-only; no new audit writes. Use show for today's score, trend for the trailing daily history.

ssg productivity show                          # today's score + five inputs
ssg productivity show --date=2026-04-10        # any past day (UTC)
ssg productivity show --json                   # machine-readable
ssg productivity trend                         # last 30 days (default)
ssg productivity trend --days=14               # custom window (1..365)
ssg productivity trend --json

Score formula (fixed, documented weighting):

score = 100
      - blocked_ratio          × 40   # friction: rules denying work
      - force_rate             × 30   # mistrust: agent overriding rules
      - retry_rate             × 20   # thrash: repeating identical calls
      - min(latency_p50 / 60s, 1) × 10 # wait time on human approvals

Result is clamped to [0, 100] and rounded to one decimal.

Five inputs (all derived from audit_log + pending_approvals):

Input	Definition
`decisions_per_min`	Evaluations per minute over the window
`blocked_ratio`	`(block + ask + deny)` / total — denied work
`force_rate`	`force` / total — agent overriding rule decisions
`retry_rate`	Fraction of evals repeating a `(tool, input)` seen within the prior 60s
`approval_latency_p50_ms`	Median seconds from pending → resolved on human approvals

Caching: today's score always recomputes; past dates are cached in the productivity_daily table. Re-invocation with the same --date is idempotent.

Tier: runs locally on the free tier. Enterprise adds cohort comparison via Fleet (separate command path).

ssg audit-sync

Push un-synced local audit log entries to the cloud dashboard (Pro/Enterprise).

ssg audit-sync                    # sync pending entries (up to 500 per run)
ssg audit-sync --dry-run          # preview what would be sent, no network call
ssg audit-sync --quiet            # suppress output (daemon/cron mode)
ssg audit-sync --url=<endpoint>   # override endpoint (testing)
ssg audit-sync --org=<slug>       # write entries under your org's scope (Enterprise)

Requirements: Pro or Enterprise plan (ssg auth login).

How it works:

Reads un-synced rows from the local audit_log SQLite table (synced = 0)
Batches up to 500 entries and POSTs to /api/v1/audit/sync
Marks synced rows (synced = 1) so they're never re-uploaded
The daemon automatically runs audit-sync every 5 minutes for Pro/Enterprise users

Privacy: Input summaries are truncated to 200 characters — full command content is never sent to the cloud.

Cloud dashboard: After syncing, view audit data at hub.sigmashake.com → Audit Dashboard.

The dashboard shows:

Decision breakdown (allow / block / ask / force) per user
Top blocked rules across the org
Per-agent (adapter) breakdown
Risk score: block rate over the selected period
Recent 100 entries with filtering by user

Enterprise org-scoped access (C-1):

Org members can aggregate audit data across all teammates using the --org=<slug> flag:

# Sync your local entries under your org's scope
ssg audit-sync --org=acme-corp

# View the org-wide dashboard (GET /api/v1/audit/dashboard?org=acme-corp)
# Caller must be a member of the org (viewer, member, admin, or owner)

Role-based access on the dashboard:

owner / admin / member: full org audit data (all users)
viewer: restricted to their own entries within the org
non-member: 403 Forbidden

ssg fleet

Enterprise fleet control plane commands. Manage machine enrollment, policy bundles, and fleet organization membership.

ssg fleet enroll --code=<code>    # Enroll this machine into a fleet org
ssg fleet status                  # Show enrollment + policy bundle status
ssg fleet status --json           # Machine-readable output
ssg fleet unenroll                # Revoke and remove fleet credentials
ssg fleet unenroll --local-only   # Remove local credentials without server revocation

Fleet enrollment flow:

Org admin generates an enrollment code in the Fleet dashboard (or via API)
Target machine runs ssg fleet enroll --code=<code>
Machine receives agent JWT + policy bundle + org configuration
ssg doctor shows Enterprise tier; policy evals use the org's bundled rules

Fleet status output:

{
  "enrolled": true,
  "org_id": "org_sigmashake",
  "org_name": "SigmaShake",
  "agent_id": "agent_abc123",
  "policy_bundle_version": 3,
  "last_sync": "2026-04-11T12:00:00Z"
}

Fleet is auth-exempt — ssg fleet enroll works before GitHub login since agent machines may not have user credentials.

See Fleet SSO Setup for configuring single sign-on with your identity provider.

Commands​

ssg auth​

ssg eval​

ssg serve​

ssg daemon​

ssg keys​

ssg check​

ssg lint​

ssg format​

ssg setup​

ssg init​

ssg new​

ssg status​

ssg doctor​

ssg list​

ssg rule​

ssg sync​

ssg push​

ssg test-rule​

ssg metrics​

ssg blocked​

ssg dedupe​

ssg flight​

ssg profile​

ssg usage​

ssg cost​

ssg publish​

ssg hub pull​

ssg hub search​

ssg hub update​

ssg hub audit​

ssg install <github-url>​

ssg orgs​

ssg certify​

ssg suggest​

ssg insights​

ssg debug​

ssg memory​

ssg workflow​

ssg productivity​

ssg audit-sync​

ssg fleet​

Commands

ssg auth

ssg eval

ssg serve

ssg daemon

ssg keys

ssg check

ssg lint

ssg format

ssg setup

ssg init

ssg new

ssg status

ssg doctor

ssg list

ssg rule

ssg sync

ssg push

ssg test-rule

ssg metrics

ssg blocked

ssg dedupe

ssg flight

ssg profile

ssg usage

ssg cost

ssg publish

ssg hub pull

ssg hub search

ssg hub update

ssg hub audit

ssg install <github-url>

ssg orgs

ssg certify

ssg suggest

ssg insights

ssg debug

ssg memory

ssg workflow

ssg productivity

ssg audit-sync

ssg fleet