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

si whoami

Parameters

None

completion

Generate shell completions.

completion bash

Generate shell completions for bash.

Syntax

si completion bash

Parameters

None

---

completion fish

Generate shell completions for fish.

Syntax

si completion fish

Parameters

None

---

completion zsh

Generate shell completions for zsh.

Syntax

si completion zsh

Parameters

None

---

login

Login to System Initiative.

Syntax

si login

Parameters

None

logout

Logout from System Initiative.

Syntax

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

si workspace switch [workspace]

Parameters

Name	Type	Required	Description
workspace	string	false	Workspace to switch to

workspace create

Create a new workspace.

Syntax

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

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

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

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

$ 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

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

# 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 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

# 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

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

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

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

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