Faramesh Docs
CLI

faramesh status

Check daemon health, lifecycle state, policy version, provider status, and current budget consumption.

faramesh status reports the runtime state of the daemon for the current stack. It's the first command you run when something looks wrong. And the command CI uses to confirm the daemon came up clean after apply.

Usage

Terminal
faramesh status [--dir DIR] [--format text|json] [--watch]
FlagDescription
--dir DIRStack directory. Defaults to the current directory.
--format text | jsonOutput format. json is stable for scripting.
--watchRefresh every two seconds until interrupted.

What it reports

Output
$ faramesh status
Daemon
  state:          READY
  pid:            42189
  uptime:         12m 34s
  socket:         /Users/you/.faramesh/runtime/faramesh.sock
  policy hash:    5b3454b7f74a03ba
  policy source:  governance.fms (applied 2026-05-17T20:44:26Z)
  runtime mode:   enforce
  os tier:        on (Seatbelt)
  WAL backend:    sqlite (./faramesh-wal)

Providers
  vault           HEALTHY    last probe: 2s ago
  kms             HEALTHY    last probe: 2s ago
  splunk-sink     DEGRADED   last error: 503 Service Unavailable (retrying)

Budgets
  daily           $84.50 / $500.00   (16.9%)
  refunds_daily   $0.00  / $5000.00  (0.0%)

Approvals
  pending:        2
  oldest age:     14m

Daemon section

FieldMeaning
stateSTARTING, INITIALIZING, READY, or HALT. SDK calls only succeed in READY.
pidProcess id from ~/.faramesh/runtime/daemon.pid.
socketUnix socket path the SDK shim and CLI talk to.
policy hashFirst 8 bytes of the AST hash. Changes on every apply.
runtime modeenforce, audit, or shadow.
os tieron (with mechanism) or off.

Providers section

Each provider declared in governance.fms reports HEALTHY, DEGRADED, or DOWN plus its last probe time. Degraded providers don't deny tool calls outright. But CREDENTIAL_UNAVAILABLE denials become more likely.

Budgets section

Per-budget consumption. Useful for confirming whether the agent has spent anything in the current window without running an audit query.

Approvals section

Count of pending approvals and the age of the oldest. If the oldest is older than your team's SLA, that's a paging signal.

Lifecycle states

The daemon goes through explicit states. status shows the current one:

StateMeaningWhat you can do
STARTINGProcess is up; no I/O yetWait
INITIALIZINGOpening WAL, replaying state, loading policy, init providersWait; SDK calls return DAEMON_NOT_READY
READYSocket open, calls evaluatedNormal operation
HALTCold-start budget exceeded or fatal init errorRead daemon logs, fix, re-apply

→ Detail: Architecture: daemon lifecycle.

Exit codes

CodeMeaning
0Daemon is READY and all providers are HEALTHY.
1Daemon is not running, or socket is missing.
2Daemon is running but in INITIALIZING (still warming up).
3Daemon is READY but at least one provider is DEGRADED or DOWN.

CI uses [ "$(faramesh status -q)" = "0" ] as a smoke check after apply.

JSON output

Terminal
faramesh status --format json
status.json
{
  "daemon": {
    "state": "READY",
    "pid": 42189,
    "uptime_seconds": 754,
    "socket": "/Users/you/.faramesh/runtime/faramesh.sock",
    "policy_hash": "5b3454b7f74a03ba",
    "policy_source": "governance.fms",
    "applied_at": "2026-05-17T20:44:26Z",
    "runtime_mode": "enforce",
    "os_tier": { "enabled": true, "mechanism": "seatbelt" },
    "wal": { "backend": "sqlite", "path": "./faramesh-wal" }
  },
  "providers": [
    { "name": "vault", "status": "HEALTHY", "last_probe_seconds_ago": 2 },
    { "name": "splunk-sink", "status": "DEGRADED", "last_error": "503 Service Unavailable" }
  ],
  "budgets": [
    { "id": "daily", "spent_usd": 84.50, "max_usd": 500.0 }
  ],
  "approvals": { "pending": 2, "oldest_age_seconds": 840 }
}

The schema is stable across patch releases.

Common scenarios

"My agent is getting DAEMON_NOT_READY"

Run faramesh status. If state is INITIALIZING, wait for READY. If it's stuck for more than your cold_start_deny_window, daemon logs (~/.faramesh/runtime/daemon.log) tell you which init step is slow.

"Calls are timing out"

Check the providers section. A DEGRADED Vault means provider broker latency is high. Calls may eventually succeed but slowly.

"Did my apply take effect?"

status shows policy hash and applied_at. Compare to the hash printed by your apply run.

"Is the daemon even running?"

Terminal
faramesh status -q
echo $?  # 0 if running and READY; 1 if not

What's next

faramesh dev

Run governance locally with in-process stubs for Vault, SPIFFE, KMS, and the audit sink. No external infrastructure.

faramesh destroy

Tear down the local stack runtime, optionally remove compiled artifacts and the WAL, and reset to a clean slate.

On this page

UsageWhat it reportsDaemon sectionProviders sectionBudgets sectionApprovals sectionLifecycle statesExit codesJSON outputCommon scenarios"My agent is getting DAEMON_NOT_READY""Calls are timing out""Did my apply take effect?""Is the daemon even running?"What's next