System Initiative

--- outline: [2, 3, 4] --- # SI CLI Reference The `si` CLI is a unified command-line tool for managing System Initiative schemas, templates, and components. ## Global Options All commands support these global options: | Option | Type | Description | Default | | ---------------------- | ------ | ---------------------------------------------- | ------------------------------------ | | `--auth-api-url <URL>` | string | Auth API endpoint URL | `https://auth-api.systeminit.com` | | `--base-url <URL>` | string | API endpoint URL | - | | `--api-token <TOKEN>` | string | Your System Initiative API token | - | | `--root <PATH>` | string | Project root directory (searches for .siroot) | Auto-discovers from current directory | | `-v, --verbose [level]`| number | Enable verbose logging (0-4) | `2` | | `--no-color` | flag | Disable colored output | - | | `-h, --help` | flag | Show help | - | | `-V, --version` | flag | Show version | - | ### Verbosity Levels - `0` - Errors only - `1` - Errors + Warnings - `2` - Errors + Warnings + Info (default) - `3` - Errors + Warnings + Info + Debug - `4` - Errors + Warnings + Info + Debug + Trace ## Environment Variables | Variable | Description | | ------------------ | ----------------------------------------------------------------- | | `SI_AUTH_API_URL` | Auth API endpoint URL | | `SI_BASE_URL` | API endpoint URL | | `SI_API_TOKEN` | Your System Initiative Workspace API token (required for authenticated commands) | | `SI_ROOT` | Project root directory (searches for .siroot if not specified) | --- ## whoami Displays authenticated user information. > Syntax ```bash si whoami ``` ### Parameters None ## completion Generate shell completions. ### completion bash Generate shell completions for bash. > Syntax ```bash si completion bash ``` #### Parameters None --- ### completion fish Generate shell completions for fish. > Syntax ```bash si completion fish ``` #### Parameters None --- ### completion zsh Generate shell completions for zsh. > Syntax ```bash si completion zsh ``` #### Parameters None --- ## login Login to System Initiative. > Syntax ```bash si login ``` ### Parameters None ## logout Logout from System Initiative. > Syntax ```bash si logout [OPTIONS] ``` ### Parameters | Name | Type | Required | Description | Default | | -------- | ---- | -------- | ----------------------------------------------------- | ------- | | --clear | flag | false | Also delete stored tokens for the current user from disk | false | ## workspace Manage workspaces you have access to. ### workspace switch Switch to a different workspace. > Syntax ```bash si workspace switch [workspace] ``` #### Parameters | Name | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | workspace | string | false | Workspace to switch to | ### workspace create Create a new workspace. > Syntax ```bash si workspace create <name> ``` #### Parameters | Name | Type | Required | Description | | ---- | ------ | -------- | ------------------- | | name | string | true | Name of workspace | ### workspace leave Leave a workspace (remove yourself as a member). > Syntax ```bash si workspace leave <workspace> ``` #### Parameters | Name | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------- | | workspace | string | true | Workspace ID or name to leave | ::: warning You cannot leave your current workspace. Switch to a different workspace first using `si workspace switch`. ::: ### workspace delete Delete a workspace (soft delete - can be recovered by contacting support). > Syntax ```bash si workspace delete <workspace> ``` #### Parameters | Name | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------- | | workspace | string | true | Workspace ID or name to delete | ::: warning You cannot delete your current workspace. Switch to a different workspace first using `si workspace switch`. To recover a deleted workspace, contact customer service at support@systeminit.com. Note that this operation will leave any existing resources running. ::: --- ### workspace members Manage workspace members (view and invite/update). #### workspace members list List all members of the current workspace. > Syntax ```bash si workspace members list ``` ##### Parameters None ##### Output Displays a table showing: - Email address - Nickname - Role (OWNER, APPROVER, or COLLABORATOR) Members are sorted by role (Owner first, then Approvers, then Collaborators). ##### Example ```bash $ si workspace members list Members of workspace "Production": Email Nickname Role alice@example.com Alice OWNER bob@example.com Bob APPROVER charlie@example.com Charlie COLLABORATOR Total members: 3 ``` --- #### workspace members manage Invite new members or update existing member roles in the current workspace. > Syntax ```bash si workspace members manage [email] [OPTIONS] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------------------------------------- | | email | string | false | Single email to invite as collaborator | | --approvers | string | false | Comma-separated list of emails to invite/update as approvers | ##### Behavior **For new members:** - Members are invited to the workspace - Default role is collaborator - Members invited with `--approvers` are promoted to approver role after invitation **For existing members:** - Detects if the user is already a member - Updates their role if different from the requested role - Supports both role upgrades (collaborator → approver) and downgrades (approver → collaborator) - Skips invitation if user already has the correct role ##### Examples ```bash # Invite a single collaborator si workspace members manage alice@example.com # Invite multiple collaborators si workspace members manage alice@example.com,bob@example.com # Invite/promote users to approvers si workspace members manage --approvers charlie@example.com,dave@example.com # Promote existing collaborator to approver si workspace members manage --approvers alice@example.com # Demote existing approver to collaborator si workspace members manage bob@example.com ``` ::: tip All members are invited as collaborators by default. Use `--approvers` to invite or promote members to the approver role, which allows them to approve change sets and invite other members. ::: --- ## change-set Manage change sets. ### change-set create Create a new change set. > Syntax ```bash si change-set create <name> ``` #### Parameters | Name | Type | Required | Description | | ---- | ------ | -------- | -------------------- | | name | string | true | Name of change set | ### change-set abandon Abandon (delete) a change set. > Syntax ```bash si change-set abandon <change-set-id-or-name> ``` #### Parameters | Name | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------- | | change-set-id-or-name | string | true | Change set ID or name | ### change-set open Open a change set in the browser. > Syntax ```bash si change-set open <change-set-id-or-name> ``` #### Parameters | Name | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------- | | change-set-id-or-name | string | true | Change set ID or name | ### change-set apply Apply a change set to HEAD. > Syntax ```bash si change-set apply <change-set-id-or-name> ``` #### Parameters | Name | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------- | | change-set-id-or-name | string | true | Change set ID or name | ### change-set list List all change sets. > Syntax ```bash si change-set list ``` #### Parameters None ## ai-agent Manages the SI AI Agent (MCP server). ### ai-agent init Initialize AI agent (one-time setup: configure token and create MCP files). > Syntax ```bash si ai-agent init [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ------------ | ------ | -------- | -------------------------------------------------------- | ----------------- | | --target-dir | string | false | Directory to create config files | Current directory | | --tool | string | false | AI tool to use: `claude`, `codex`, `opencode`, `cursor` | - | ### ai-agent start Launch Claude Code (MCP server starts automatically). > Syntax ```bash si ai-agent start [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ------ | ------ | -------- | -------------------------------- | -------- | | --tool | string | false | AI tool to launch | `claude` | ### ai-agent config View or update AI agent configuration. > Syntax ```bash si ai-agent config [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | -------------- | ------ | -------- | -------------------------------------------------------- | ------- | | --show | flag | false | Show current configuration (default if no other options) | false | | --update-token | flag | false | Update the API token | false | | --tool | string | false | Update the AI tool: `claude`, `cursor`, `windsurf`, `none` | - | ### ai-agent stdio Run MCP server in stdio mode (for external AI tools to connect). > Syntax ```bash si ai-agent stdio ``` #### Parameters None ## schema Manage schemas: initialize project, generate functions locally, pull from and push to remote workspaces. ### schema init Initialize a new System Initiative project in the current or specified directory. > Syntax ```bash si schema init [ROOT_PATH] ``` #### Parameters | Name | Type | Required | Description | Default | | --------- | ------ | -------- | ----------------------- | ----------------- | | ROOT_PATH | string | false | Directory to initialize | Current directory | ### schema action generate Generate action functions for schemas. > Syntax ```bash si schema action generate [SCHEMA_NAME] [ACTION_NAME] ``` #### Parameters | Name | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------------ | | SCHEMA_NAME | string | false | Name of the schema | | ACTION_NAME | string | false | Action name: `create`, `destroy`, `refresh`, `update` | ### schema authentication generate Generate authentication functions for schemas. > Syntax ```bash si schema authentication generate [SCHEMA_NAME] [AUTH_NAME] ``` #### Parameters | Name | Type | Required | Description | | ----------- | ------ | -------- | ----------------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | AUTH_NAME | string | false | Name of the authentication function | ### schema codegen generate Generate code generator functions for schemas. > Syntax ```bash si schema codegen generate [SCHEMA_NAME] [CODEGEN_NAME] ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | -------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | CODEGEN_NAME | string | false | Name of the code generator | ### schema management generate Generate management functions for schemas. > Syntax ```bash si schema management generate [SCHEMA_NAME] [MANAGEMENT_NAME] ``` #### Parameters | Name | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | MANAGEMENT_NAME | string | false | Name of the management function | ### schema qualification generate Generate qualification functions for schemas. > Syntax ```bash si schema qualification generate [SCHEMA_NAME] [QUALIFICATION_NAME] ``` #### Parameters | Name | Type | Required | Description | | ------------------ | ------ | -------- | ---------------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | QUALIFICATION_NAME | string | false | Name of the qualification function | ### schema scaffold generate Generate a complete schema scaffold with all default functions. > Syntax ```bash si schema scaffold generate [SCHEMA_NAME] ``` #### Parameters | Name | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------ | | SCHEMA_NAME | string | false | Name of the schema to scaffold | ### schema pull Pulls schemas from your remote System Initiative workspace. Supports wildcard patterns like `Fastly::*` to pull all schemas in a category, or `*` to pull all schemas. > Syntax ```bash si schema pull [SCHEMA_NAME...] ``` #### Parameters | Name | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------- | | SCHEMA_NAME | string[] | false | Schema names to pull (supports wildcards) | | --builtins | flag | false | Include builtin schemas (schemas you don't own) | ### schema push Pushes schemas to your remote System Initiative workspace. > Syntax ```bash si schema push [SCHEMA_NAME...] ``` #### Parameters | Name | Type | Required | Description | | ----------------------- | -------- | -------- | -------------------------------------------------- | | SCHEMA_NAME | string[] | false | Schema names to push | | -s, --skip-confirmation | flag | false | Skip confirmation prompt | | -b, --update-builtins | flag | false | Change builtin schema, without creating overlays | --- ### schema contribute Contribute a schema to the module index (works on HEAD change set only). > Syntax ```bash si schema contribute <SCHEMA> ``` #### Parameters | Name | Type | Required | Description | | ------ | ------ | -------- | ------------------- | | SCHEMA | string | true | Name of the schema | --- ### schema overlay Manage schema overlays: generate overlay functions and push them to remote workspaces. #### schema overlay action generate Generate action overlay functions. > Syntax ```bash si schema overlay action generate [SCHEMA_NAME] [OVERLAY_NAME] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | OVERLAY_NAME | string | false | Name of the action overlay | #### schema overlay authentication generate Generate authentication overlay functions. > Syntax ```bash si schema overlay authentication generate [SCHEMA_NAME] [OVERLAY_NAME] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------ | | SCHEMA_NAME | string | false | Name of the schema | | OVERLAY_NAME | string | false | Name of the authentication overlay | #### schema overlay codegen generate Generate code generator overlay functions. > Syntax ```bash si schema overlay codegen generate [SCHEMA_NAME] [OVERLAY_NAME] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | OVERLAY_NAME | string | false | Name of the codegen overlay | #### schema overlay management generate Generate management overlay functions. > Syntax ```bash si schema overlay management generate [SCHEMA_NAME] [OVERLAY_NAME] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | OVERLAY_NAME | string | false | Name of the management overlay | #### schema overlay qualification generate Generate qualification overlay functions. > Syntax ```bash si schema overlay qualification generate [SCHEMA_NAME] [OVERLAY_NAME] ``` ##### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------- | | SCHEMA_NAME | string | false | Name of the schema | | OVERLAY_NAME | string | false | Name of the qualification overlay | #### schema overlay push Pushes overlay funcs to your remote System Initiative workspace. > Syntax ```bash si schema overlay push [SCHEMA_NAME...] ``` ##### Parameters | Name | Type | Required | Description | | ----------- | -------- | -------- | ------------------------------- | | SCHEMA_NAME | string[] | false | Schema names (overlays) to push | ## component Component-related operations. ### component get Get component data by name or ID. > Syntax ```bash si component get <component> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ---------------- | ------ | -------- | ------------------------------------------------ | ------- | | component | string | true | Component name or ID | - | | -c, --change-set | string | false | Change set ID or name | `HEAD` | | -o, --output | string | false | Output format: `info`, `json`, or `yaml` | `info` | | --cache | string | false | Cache output to file; format determined by file extension (.json, .yaml, .yml) | - | | --raw | flag | false | Output raw API response as JSON and exit | false | ### component create Create component from JSON/YAML file (idempotent). > Syntax ```bash si component create <input-file> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ---------------- | ------ | -------- | ------------------------------------------------ | ------- | | input-file | string | true | Path to input file (JSON or YAML) | - | | -c, --change-set | string | false | Change set ID or name | `HEAD` | | -o, --output | string | false | Output format: `info`, `json`, or `yaml` | `info` | | --cache | string | false | Cache output to file; format determined by file extension | - | | --raw | flag | false | Output raw API response as JSON and exit | false | ### component update Update a component from JSON/YAML file (idempotent). > Syntax ```bash si component update <input-file> --change-set <id-or-name> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------- | | input-file | string | true | Path to input file (JSON or YAML) | | -c, --change-set | string | true | Change set ID or name | | --component | string | false | Component ID or name (overrides componentId from file)| | --dry-run | flag | false | Show diff without applying changes | ### component delete Delete a component by name or ID. > Syntax ```bash si component delete <component> --change-set <id-or-name> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------ | | component | string | true | Component name or ID | | -c, --change-set | string | true | Change set ID or name | | --dry-run | flag | false | Preview deletion without applying changes | ### component erase Erase a component by name or ID. > Syntax ```bash si component erase <component> --change-set <id-or-name> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------- | | component | string | true | Component name or ID | | -c, --change-set | string | true | Change set ID or name | | --dry-run | flag | false | Preview deletion without applying changes | ### component search Search for components using a search query. > Syntax ```bash si component search <query> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ----------------- | -------- | -------- | ----------------------------------------------------- | ------- | | query | string | true | Search query | - | | -c, --change-set | string | false | Change set ID or name | `HEAD` | | -o, --output | string | false | Output format: `info`, `json`, or `yaml` | `info` | | -a, --attribute | string[] | false | Attribute paths to include in output (repeatable) | - | | --full-component | flag | false | Show full component details for each result | false | ### component upgrade Upgrade component(s) to the latest schema version. This command checks if components can be upgraded before creating a change set, preventing orphaned change sets for no-op operations. If no change set is specified, it automatically creates one with a descriptive name. > Syntax ```bash # Upgrade a specific component si component upgrade <component> [OPTIONS] # Upgrade all upgradable components si component upgrade --all [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ------------------ | ------ | -------- | ---------------------------------------------------------------- | ------- | | component | string | false | Component name or ID (required unless --all is specified) | - | | -c, --change-set | string | false | Change set ID or name (creates new change set if not specified) | - | | --all | flag | false | Upgrade all upgradable components (required if no component specified) | false | | --schema-category | string | false | Filter by schema category (e.g., `AWS::EC2`) when using --all | - | | --dry-run | flag | false | Preview upgrades without applying changes | false | #### Examples ```bash # Upgrade a specific component (auto-creates change set) si component upgrade my-ec2-instance # Upgrade a component in an existing change set si component upgrade my-s3-bucket -c my-changes # Upgrade all upgradable components si component upgrade --all # Upgrade only AWS::EC2 components si component upgrade --all --schema-category AWS::EC2 # Preview what would be upgraded si component upgrade --all --dry-run ``` #### Behavior - Checks if components can be upgraded in HEAD **before** creating a change set - If nothing can be upgraded, exits cleanly without creating a change set - For bulk upgrades (`--all`), processes components one at a time - Individual component failures don't stop bulk upgrades - Auto-created change sets are abandoned on error - Returns exit code 1 if any components fail to upgrade #### Notes - Components can only be upgraded in a change set, not on HEAD - The `canBeUpgraded` flag indicates if a newer schema version is available - Use `--schema-category` to filter bulk upgrades (e.g., `AWS::EC2`, `Hetzner::Cloud`) - Schema category filters use the format `Provider::Service` (e.g., `Microsoft.Network` won't work, use `Microsoft`) ## secret Manage secrets and credentials. ### secret create Create a new secret. > Syntax ```bash si secret create <secret-type> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ------------------- | ------ | -------- | -------------------------------------------------------- | ------- | | secret-type | string | true | Type of secret to create | - | | --name | string | false | Name for the secret instance | - | | --description | string | false | Description for the secret | - | | -c, --change-set | string | false | Change set ID or name (creates new change set if not specified) | - | | --use-local-profile | flag | false | Discover credentials from local environment (e.g., AWS credentials) | false | | --interactive | flag | false | Prompt for all values interactively | false | | --dry-run | flag | false | Show what would be created without making changes | false | ### secret update Update an existing secret by component name or ID. > Syntax ```bash si secret update <component-name-or-id> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | ------------------- | ------ | -------- | -------------------------------------------------------- | ------- | | component-name-or-id| string | true | Component name or ID | - | | --name | string | false | New name for the secret | - | | --description | string | false | New description for the secret | - | | -c, --change-set | string | false | Change set ID or name (creates new change set if not specified) | - | | --use-local-profile | flag | false | Discover credentials from local environment (e.g., AWS credentials) | false | | --interactive | flag | false | Prompt for all values interactively | false | | --dry-run | flag | false | Show what would be updated without making changes | false | ## template Manages System Initiative templates. ### template generate Generate a new template structure file. > Syntax ```bash si template generate <name> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | Default | | --------------- | ------ | -------- | ------------------------------------------------ | ----------------- | | name | string | true | Name of the template | - | | -o, --output-dir| string | false | Output directory for the template file | Current directory | ### template run Run a SI template file (local path or remote URL). > Syntax ```bash si template run <template> --key <invocationKey> [OPTIONS] ``` #### Parameters | Name | Type | Required | Description | | --------------------- | ------ | -------- | ----------------------------------------------------- | | template | string | true | Path to template file or remote URL | | -k, --key | string | true | Invocation key for the template; used for idempotency | | -i, --input | string | false | Path to input data file (JSON or YAML); validated against template's input schema | | -b, --baseline | string | false | Path to baseline data file (JSON or YAML) | | -c, --cache-baseline | string | false | Path to cache baseline results; format determined by file extension (.json, .yaml, .yml) | | --cache-baseline-only | flag | false | Exit after writing baseline cache (requires --cache-baseline) | | --dry-run | flag | false | Show planned changes without executing them |