Skip to main content

​
CLI Reference

This page is the fast orientation guide for si. For a full categorized list, use Command Reference.

​
Command discovery pattern

si --help
si <command> --help
si <command> <subcommand> --help

​
CLI color system

SI text output uses a small semantic palette instead of per-command ad hoc colors:
RoleMeaningColor
Section headingsusage blocks, help sections, command-group titlescyan
Commands and examplescommand names, runnable examples, selected profilesmagenta
Flags and operator promptsoptions, warnings, confirmation promptsyellow
Labelskey=value keys, field names, probe labelsblue
Successready, ok, warmed, healthy stategreen
Warningdegraded or operator-attention stateyellow
Errorfailed, invalid, destructive/error statered
Mutedindexes, separators, filler textgray
Rules:
  • JSON output stays uncolored.
  • Text output uses the semantic palette above when color is enabled.
  • si --help and nested --help output use the same palette as runtime text output.
Color control:
  • SI_CLI_COLOR=always: force color even when stdout is not a TTY
  • SI_CLI_COLOR=auto: default behavior
  • SI_CLI_COLOR=never: disable CLI colors
  • NO_COLOR=1: disable CLI colors

​
Top-level command families

DomainCommands
Runtime and orchestrationsi codex, si surf, si viva
Secrets and contextsi vault (si creds), si fort, si settings
Third-party integrationsUse the standalone orbit <provider> ... CLI from Aureuma/orbit; si image remains in SI for image bridge workflows.
Build and releasesi build, si commands, si version, si help

​
High-signal workflows

​
Runtime setup

si codex spawn --profile default --workspace "$PWD"
si codex stop --profile default --slot review
si codex list

​
Viva tunnel via SI wrapper

si viva config set --repo ~/Development/viva --build true
si viva config tunnel import --profile dev --file ~/Development/safe/viva/cloudflare.tunnel.dev.toml --set-default
si viva config tunnel default --profile dev
si viva config tunnel show --json
si viva -- tunnel up --profile dev
si viva -- tunnel status --profile dev
si viva -- tunnel down --profile dev

​
Integration readiness

orbit list --json
orbit github doctor --json
orbit cloudflare doctor --json
orbit gcp doctor --json

​
Fort runtime secret check

si fort doctor
si fort get --repo github --env dev --key RM_GITHUB_TOKEN

​
Release preflight

si build self assets --out-dir .artifacts/release-preflight
orbit github release create Aureuma/si --tag vX.Y.0 --title "vX.Y.0" --target "$(git rev-parse HEAD)" --draft
  • si build self assets defaults to the canonical SI workspace version from root Cargo.toml.
  • For SI itself, release tags come from that same repo-wide version and only minor releases are tagged/published.
  • orbit github release create now verifies the remote tag first.
  • When the tag is missing, pass --target <sha> and SI will create the git tag ref before creating the release.
  • For draft releases, GitHub may still return an untagged-... HTML URL until publish; verify with tag_name and git ls-remote --tags.

​
Faster Rust iteration

si build self check --timings
si build self --timings
  • si build self now reuses .artifacts/cargo-target/self-build by default for faster rebuilds.
  • si build self check runs cargo check against the SI CLI manifest without linking a release binary.
  • si build self and release-asset builds auto-use sccache when it is available on PATH.
  • Keep SI’s .artifacts/cargo-target warm during active development. Prune it only when artifacts are older than 14 days or when root disk pressure requires immediate recovery; clear repo target directories before clearing sccache so cross-repo Rust rebuilds stay fast.

​
Safety guidance

  • On host/admin flows, use si fort run -- <command> when secrets are required.
  • For SI runtime workers, use si fort ... for secret access.
  • si fort wrapper passes explicit Fort file-path auth flags for the managed Codex profile session under CODEX_HOME/fort/; caller-supplied FORT_TOKEN_PATH / FORT_REFRESH_TOKEN_PATH values are not normal runtime fallbacks.
  • Runtime secret commands fail loudly when no usable runtime Fort session exists; bootstrap/admin token files are only for explicit admin/provisioning commands.
  • If a flag belongs to the native fort CLI, pass it after -- (example: si fort -- --host https://fort.aureuma.ai doctor).
  • Prefer --json for automation and auditability.
  • Run doctor commands before mutating production systems.
  • Keep command docs aligned with si --help and si help --format json. orbit github release create now follows the checkout-first default path more closely:
  • omit the repo argument inside a GitHub checkout and SI infers it from origin
  • use -R, --repo <owner/repo> when you need an explicit override
  • omit --title to reuse the release tag as the title