Skip to content
grafOS docs

grafos fabric

Fabric-wide views: cells, resources, dashboard. Operator-leaning.

grafos fabric

Unified fabric view: status, resources, cells, schedulers, events, dashboard. Aggregates state across providers and scheduler modes


Usage: grafos fabric [OPTIONS] <COMMAND>


Commands:
  status      Show tenant, scheduler URL, scheduler health, registered cells, provider readiness summary, and outstanding warnings
  cells       List provider cells with identity, scheduler attachment, inventory freshness, and lease counts (pending / confirmed / fenced). Read-only
  resources   Aggregate resource capacity (memory / CPU) across registered cells. Per-cell rows + per-(provider, kind) rollup totals. Read-only; reads scheduler-backed `/api/v1/cells` (never stale local files)
  dashboard   Open the tenant dashboard in the system browser using the active context. Prints the URL if the browser launch fails or `--print-url` is set (useful for SSH / CI / locked-down desktops). Does NOT pass any bearer token through the URL
  schedulers  Show the registered scheduler chain: authority role, durability mode, leader epoch, mode (orchestrator vs cell). Today reports the single active scheduler the CLI is pointed at; the shape is forward-compatible for when multi-scheduler tenancy lands
  events      Tail tenant-scoped audit/admission/run/provider events with filters for event type and time window. Polls `/api/v1/events?last_id=N` (server-side tenant scoping is applied by the auth context). Ctrl+C to exit; `--once` prints the current buffer and returns
  help        Print this message or the help of the given subcommand(s)


Options:
      --fabric <FABRIC>  Fabric address (host:port). Overrides GRAFOS_FABRIC env var [env: GRAFOS_FABRIC=]
      --json             Output in JSON format for scripting
      --wide             Show additional columns in table output
      --no-color         Disable color output
      --pool <POOL>      Pool name (default: "default") [default: default]
  -h, --help             Print help
  -V, --version          Print version

grafos fabric status

Show tenant, scheduler URL, scheduler health, registered cells, provider readiness summary, and outstanding warnings.


Read-only. Does not mutate scheduler state.


Usage: grafos fabric status [OPTIONS]


Options:
      --fabric <FABRIC>
          Fabric address (host:port). Overrides GRAFOS_FABRIC env var


          [env: GRAFOS_FABRIC=]


      --scheduler <SCHEDULER>
          Override the scheduler URL. Highest priority — overrides `GRAFOS_SCHEDULER` and any Tenura-hosted credential


          [env: GRAFOS_SCHEDULER=]


      --bearer <BEARER>
          FabricAdmin bearer (only required against a scheduler with `--auth-mode mtls+token` or similar). For Tenura-hosted use, the bearer is read from credentials.json automatically


          [env: GRAFOS_BEARER=]


      --cert <CERT>
          mTLS client cert (PEM). Pass alongside `--key` and `--ca` for schedulers with `--auth-mode mtls`


          [env: GRAFOS_CERT=]


      --wide
          Show additional columns in table output


      --key <KEY>
          Client private key (PEM) matching --cert


          [env: GRAFOS_KEY=]


      --no-color
          Disable color output


      --ca <CA>
          CA bundle (PEM) used to verify the orchestrator's TLS cert. Required when the orchestrator is signed by a fabric CA not in the public WebPKI set


          [env: GRAFOS_CA=]


      --pool <POOL>
          Pool name (default: "default")


          [default: default]


      --json
          Emit machine-readable JSON instead of the human-readable table. The shape is intentionally identical to what the dashboard and agent skill consume so all three paths see the same fabric state


  -h, --help
          Print help (see a summary with '-h')


  -V, --version
          Print version

grafos fabric cells

List provider cells with identity, scheduler attachment, inventory freshness, and lease counts (pending / confirmed / fenced). Read-only


Usage: grafos fabric cells [OPTIONS]


Options:
      --fabric <FABRIC>        Fabric address (host:port). Overrides GRAFOS_FABRIC env var [env: GRAFOS_FABRIC=]
      --scheduler <SCHEDULER>  Override the scheduler URL. Highest priority — overrides `GRAFOS_SCHEDULER` and any Tenura-hosted credential [env: GRAFOS_SCHEDULER=]
      --bearer <BEARER>        FabricAdmin bearer token (alternative to --cert/--key/--ca when the orchestrator is in mtls+token / token mode) [env: GRAFOS_BEARER=]
      --cert <CERT>            Client certificate (PEM) for mTLS to the orchestrator. Pair with --key + --ca; same auth surface used by `grafos cloud connect` and `grafos admin` [env: GRAFOS_CERT=]
      --key <KEY>              Client private key (PEM) matching --cert [env: GRAFOS_KEY=]
      --no-color               Disable color output
      --ca <CA>                CA bundle (PEM) used to verify the orchestrator's TLS cert. Required when the orchestrator is signed by a fabric CA not in the public WebPKI set [env: GRAFOS_CA=]
      --pool <POOL>            Pool name (default: "default") [default: default]
      --provider <PROVIDER>    Filter to cells of a specific provider (e.g. `aws`, `gcp`)
      --health <HEALTH>        Filter to cells in a specific health state [possible values: healthy, unhealthy]
      --wide                   Show extended columns: heartbeat age, fence count, leader epoch, control mode
      --json                   Emit machine-readable JSON. Stable shape with `schema_version: 1` so dashboards and agent tooling consume identical state
  -h, --help                   Print help
  -V, --version                Print version

grafos fabric resources

Aggregate resource capacity (memory / CPU) across registered cells. Per-cell rows + per-(provider, kind) rollup totals. Read-only; reads scheduler-backed `/api/v1/cells` (never stale local files).


Block + GPU resources are reported as `null` until they're surfaced through the orchestrator's cell summary.


Usage: grafos fabric resources [OPTIONS]


Options:
      --fabric <FABRIC>
          Fabric address (host:port). Overrides GRAFOS_FABRIC env var


          [env: GRAFOS_FABRIC=]


      --scheduler <SCHEDULER>
          Orchestrator URL. Falls back to `GRAFOS_SCHEDULER`, then to the Tenura-hosted credentials when that context applies


          [env: GRAFOS_SCHEDULER=]


      --bearer <BEARER>
          FabricAdmin bearer token (alternative to --cert/--key/--ca when the orchestrator is in mtls+token / token mode)


          [env: GRAFOS_BEARER=]


      --cert <CERT>
          Client certificate (PEM) for mTLS to the orchestrator. Pair with --key + --ca; same auth surface used by `grafos cloud connect` and `grafos admin`


          [env: GRAFOS_CERT=]


      --wide
          Show additional columns in table output


      --key <KEY>
          Client private key (PEM) matching --cert


          [env: GRAFOS_KEY=]


      --no-color
          Disable color output


      --ca <CA>
          CA bundle (PEM) used to verify the orchestrator's TLS cert. Required when the orchestrator is signed by a fabric CA not in the public WebPKI set


          [env: GRAFOS_CA=]


      --pool <POOL>
          Pool name (default: "default")


          [default: default]


      --provider <PROVIDER>
          Filter to cells of a specific provider


      --kind <KIND>
          Filter to a specific resource kind. `mem` and `cpu` are available today; `block` and `gpu` are reserved for when the orchestrator surfaces them (currently always reported as `null` per-cell)


          [possible values: mem, cpu, block, gpu]


      --json
          Emit machine-readable JSON


  -h, --help
          Print help (see a summary with '-h')


  -V, --version
          Print version

grafos fabric dashboard

Open the tenant dashboard in the system browser using the active context. Prints the URL if the browser launch fails or `--print-url` is set (useful for SSH / CI / locked-down desktops). Does NOT pass any bearer token through the URL


Usage: grafos fabric dashboard [OPTIONS]


Options:
      --dashboard <DASHBOARD>  Override the dashboard URL. Falls back to `GRAFOS_DASHBOARD_URL` env, then to the design-doc default (`https://dashboard.grafos.tenura.systems`) when running against a Tenura-hosted context. For `--scheduler` overrides without an explicit dashboard URL, the command fails closed with a clear hint [env: GRAFOS_DASHBOARD_URL=]
      --fabric <FABRIC>        Fabric address (host:port). Overrides GRAFOS_FABRIC env var [env: GRAFOS_FABRIC=]
      --print-url              Don't launch the system browser; just print the URL. Useful for SSH sessions, CI, and locked-down desktops
      --scheduler <SCHEDULER>  Same scheduler-context plumbing as the other fabric subcommands so an operator switching between contexts (e.g. local dev fabric) sees a friendly "no dashboard configured for this context" message instead of being dropped onto a broken Tenura URL [env: GRAFOS_SCHEDULER=]
      --wide                   Show additional columns in table output
      --bearer <BEARER>        FabricAdmin bearer token (alternative to --cert/--key/--ca when the orchestrator is in mtls+token / token mode) [env: GRAFOS_BEARER=]
      --no-color               Disable color output
      --json                   Emit the resolved dashboard URL + context as JSON instead of human-readable output. Implies `--print-url` (no browser launch). Lets the agent skill and dashboard tooling consume the same shape every other fabric subcommand emits
      --pool <POOL>            Pool name (default: "default") [default: default]
  -h, --help                   Print help
  -V, --version                Print version

grafos fabric schedulers

Show the registered scheduler chain: authority role, durability mode, leader epoch, mode (orchestrator vs cell). Today reports the single active scheduler the CLI is pointed at; the shape is forward-compatible for when multi-scheduler tenancy lands


Usage: grafos fabric schedulers [OPTIONS]


Options:
      --fabric <FABRIC>        Fabric address (host:port). Overrides GRAFOS_FABRIC env var [env: GRAFOS_FABRIC=]
      --scheduler <SCHEDULER>  Orchestrator URL. Falls back to `GRAFOS_SCHEDULER`, then to the Tenura-hosted credentials when that context applies  [env: GRAFOS_SCHEDULER=]
      --bearer <BEARER>        FabricAdmin bearer token (alternative to --cert/--key/--ca when the orchestrator is in mtls+token / token mode) [env: GRAFOS_BEARER=]
      --cert <CERT>            Client certificate (PEM) for mTLS to the orchestrator. Pair with --key + --ca; same auth surface used by `grafos cloud connect` and `grafos admin` [env: GRAFOS_CERT=]
      --wide                   Show additional columns in table output
      --key <KEY>              Client private key (PEM) matching --cert [env: GRAFOS_KEY=]
      --no-color               Disable color output
      --ca <CA>                CA bundle (PEM) used to verify the orchestrator's TLS cert. Required when the orchestrator is signed by a fabric CA not in the public WebPKI set [env: GRAFOS_CA=]
      --pool <POOL>            Pool name (default: "default") [default: default]
      --json
  -h, --help                   Print help
  -V, --version                Print version

grafos fabric events

Tail tenant-scoped audit/admission/run/provider events with filters for event type and time window. Polls `/api/v1/events?last_id=N` (server-side tenant scoping is applied by the auth context). Ctrl+C to exit; `--once` prints the current buffer and returns


Usage: grafos fabric events [OPTIONS]


Options:
      --fabric <FABRIC>          Fabric address (host:port). Overrides GRAFOS_FABRIC env var [env: GRAFOS_FABRIC=]
      --scheduler <SCHEDULER>    Orchestrator URL. Falls back to `GRAFOS_SCHEDULER`, then to the Tenura-hosted credentials when that context applies  [env: GRAFOS_SCHEDULER=]
      --bearer <BEARER>          FabricAdmin bearer token (alternative to --cert/--key/--ca when the orchestrator is in mtls+token / token mode) [env: GRAFOS_BEARER=]
      --cert <CERT>              Client certificate (PEM) for mTLS to the orchestrator. Pair with --key + --ca; same auth surface used by `grafos cloud connect` and `grafos admin` [env: GRAFOS_CERT=]
      --wide                     Show additional columns in table output
      --key <KEY>                Client private key (PEM) matching --cert [env: GRAFOS_KEY=]
      --no-color                 Disable color output
      --ca <CA>                  CA bundle (PEM) used to verify the orchestrator's TLS cert. Required when the orchestrator is signed by a fabric CA not in the public WebPKI set [env: GRAFOS_CA=]
      --pool <POOL>              Pool name (default: "default") [default: default]
      --event-type <EVENT_TYPE>  Filter events by event_type (client-side substring match). Repeatable — multiple flags act as OR. Examples: `--event-type lease_granted --event-type lease_denied`
      --once                     Print the current buffer and exit, instead of tail-following
      --interval <INTERVAL>      Polling interval (seconds) between fetches in tail-follow mode. Default 2s; the scheduler's event ring buffer holds 256 events, so a poll faster than ~event-rate guarantees no loss [default: 2]
      --since-id <SINCE_ID>      Start from a specific event id rather than the buffer's current head. Useful for replay from a known checkpoint [default: 0]
      --json                     Emit one JSON object per event (newline-delimited) instead of the human-readable line format
  -h, --help                     Print help
  -V, --version                  Print version