SI CLI

Updated November 28, 2025.

The si CLI is a unified command-line tool for managing System Initiative schemas, templates, and components. It provides comprehensive tooling for schema management, template execution, component operations, and AI agent integration.

Overview

The si CLI allows you to:

Manage Schemas: Author and manage System Initiative schemas locally, generate functions, and sync with remote workspaces
Execute Templates: Run infrastructure-as-code templates with convergence and idempotency
Operate on Components: Get, update, delete, and search components programmatically
Integrate AI Agents: Set up and manage AI coding assistants (Claude Code, Cursor, Windsurf) with the bundled MCP server
Sync with Workspaces: Push and pull schemas and overlays from your remote workspaces

Installation

Quick Install (Recommended)

The easiest way to install the SI CLI is using our installation script:

Linux & macOS

Basic Installation:

bash

# Install for current user (recommended)
curl -fsSL https://auth.systeminit.com/install.sh | sh

This installs to your user directory ($HOME/.local/bin or $HOME/bin). No sudo required!

System-wide Installation:

bash

# Install for all users (requires sudo)
curl -fsSL https://auth.systeminit.com/install.sh | sudo sh

This installs to /usr/local/bin, making it available to all users on the system.

TIP

For most users, the user installation is recommended. It doesn't require admin privileges and works perfectly for personal development.

What the script does:

Automatically detects your platform (Linux/macOS) and architecture (x86_64/aarch64)
Downloads the latest stable release
Extracts and installs the binary with correct permissions
On macOS: automatically removes quarantine attributes so the binary runs without security prompts
Intelligently selects installation directory based on your PATH and whether you use sudo

Installation Options:

bash

# Install specific version
curl -fsSL https://auth.systeminit.com/install.sh | sh -s -- -V stable

# Install to custom location
curl -fsSL https://auth.systeminit.com/install.sh | sh -s -- -d ~/.local/bin

# Install specific platform
curl -fsSL https://auth.systeminit.com/install.sh | sh -s -- -p darwin-aarch64

# See all options
curl -fsSL https://auth.systeminit.com/install.sh | sh -s -- --help

INFO

The installation script supports:

Linux: x86_64, aarch64
macOS: x86_64 (Intel), aarch64 (Apple Silicon)

For Windows, see the Windows installation instructions below.

Windows

Quick Install (PowerShell):

powershell

# Run the installation script
irm https://auth.systeminit.com/install.ps1 | iex

The script will:

Automatically detect your system architecture (x86_64)
Download the latest stable release
Extract and install the binary
Add to your PATH automatically
Install to $env:LOCALAPPDATA\si (user install) or C:\Program Files\si (admin)

Run as Administrator (optional, for system-wide install):

powershell

# Right-click PowerShell and select "Run as Administrator", then:
irm https://auth.systeminit.com/install.ps1 | iex

TIP

For most users, the regular (non-admin) installation works great. It installs to your user directory and doesn't require administrator privileges.

PowerShell Alias Conflict

PowerShell has a built-in alias si for the Set-Item cmdlet. After installation, use si.exe to run commands:

powershell

si.exe --version
si.exe --help

Alternatively, remove the alias by adding this to your PowerShell profile ($PROFILE):

powershell

Remove-Item alias:si -Force -ErrorAction SilentlyContinue

Installation Options:

powershell

# Download and run with options
Invoke-WebRequest https://auth.systeminit.com/install.ps1 -OutFile install.ps1
.\install.ps1 -Help
.\install.ps1 -Destination "C:\Tools\si"
.\install.ps1 -Version "stable"

Manual Installation

If you prefer to download and install manually:

Linux (aarch64)

bash

curl -LO https://artifacts.systeminit.com/si/stable/binary/linux/aarch64/si-stable-binary-linux-aarch64.tar.gz
tar -xzf si-stable-binary-linux-aarch64.tar.gz
sudo mv si /usr/local/bin/
# Or move to user bin: mv si ~/.local/bin/

Linux (x86_64)

bash

curl -LO https://artifacts.systeminit.com/si/stable/binary/linux/x86_64/si-stable-binary-linux-x86_64.tar.gz
tar -xzf si-stable-binary-linux-x86_64.tar.gz
sudo mv si /usr/local/bin/
# Or move to user bin: mv si ~/.local/bin/

macOS (Apple Silicon)

bash

curl -LO https://artifacts.systeminit.com/si/stable/binary/darwin/aarch64/si-stable-binary-darwin-aarch64.tar.gz
tar -xzf si-stable-binary-darwin-aarch64.tar.gz
sudo mv si /usr/local/bin/
# Or move to user bin: mv si ~/.local/bin/

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/si

macOS (Intel)

bash

curl -LO https://artifacts.systeminit.com/si/stable/binary/darwin/x86_64/si-stable-binary-darwin-x86_64.tar.gz
tar -xzf si-stable-binary-darwin-x86_64.tar.gz
sudo mv si /usr/local/bin/
# Or move to user bin: mv si ~/.local/bin/

# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/si

Windows (x86_64)

Using PowerShell:

powershell

# Download the binary
Invoke-WebRequest -Uri https://artifacts.systeminit.com/si/stable/binary/windows/x86_64/si-stable-binary-windows-x86_64.zip -OutFile si.zip

# Extract the binary
Expand-Archive -Path si.zip -DestinationPath .

# Move to a directory in your PATH (example: C:\Program Files\si)
New-Item -ItemType Directory -Force -Path "C:\Program Files\si"
Move-Item -Path .\si.exe -Destination "C:\Program Files\si\si.exe"

# Add to PATH (requires admin privileges)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\si", [EnvironmentVariableTarget]::Machine)

Using Command Prompt (cmd):

cmd

REM Download the binary (requires curl, available in Windows 10+)
curl -LO https://artifacts.systeminit.com/si/stable/binary/windows/x86_64/si-stable-binary-windows-x86_64.zip

REM Extract using tar (available in Windows 10+)
tar -xf si-stable-binary-windows-x86_64.zip

REM Move to a directory in your PATH
move si.exe "C:\Program Files\si\si.exe"

REM Add to PATH (requires admin privileges)
setx /M PATH "%PATH%;C:\Program Files\si"

Global Options

All commands support these global options:

Option	Type	Description	Default
`--api-token <TOKEN>`	string	Your System Initiative API token	-
`--api-base-url <URL>`	string	API endpoint URL	`https://api.systeminit.com`
`--root <PATH>`	string	Project root directory (rarely needed - see below)	Auto-discovers from current directory
`-v, --verbose [level]`	number	Verbose logging (0-4)	`2`
`--no-color`	flag	Disable colored output	-
`-h, --help`	flag	Show help	-
`-V, --version`	flag	Show version	-

Project Root Discovery

By default, the CLI automatically finds your project root by searching upward from your current directory for a .siroot marker file. This means you can run si commands from anywhere inside your project - just like Git.

The --root option is only needed in these scenarios:

Scripts that need to explicitly specify a project
CI/CD environments
Working with multiple projects simultaneously
When you're outside a project and want to target a specific one

Example of automatic discovery:

bash

# Works from anywhere in your project
cd /path/to/project/schemas/AWS::EC2::Instance
si schema generate action "AWS::EC2::Instance" create  # ← Finds .siroot automatically

# Or from project root
cd /path/to/project
si schema generate action "AWS::EC2::Instance" create

Example with explicit root:

bash

# Useful for scripts or when outside the project
si --root /path/to/project schema generate action "AWS::EC2::Instance" create

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_API_TOKEN`	System Initiative API token (required for authenticated commands)
`SI_API_BASE_URL`	API endpoint URL
`SI_BASE_URL`	API base URL for templates
`SI_ROOT`	Project root directory (rarely needed - auto-discovers by default)

Setting Up Authentication

Most si commands require authentication via the SI_API_TOKEN environment variable. Rather than prefixing every command with SI_API_TOKEN=..., we recommend setting it in your shell session or profile:

For a single session (Linux/macOS):

bash

# Set for current terminal session
export SI_API_TOKEN=your_token_here

# Now all commands work without the prefix
si whoami
si schema pull "*"
si component search 'schemaName:"AWS EC2 Instance"'

For a single session (Windows PowerShell):

powershell

# Set for current PowerShell session
$env:SI_API_TOKEN="your_token_here"

# Now all commands work without the prefix
si whoami
si schema pull "*"
si component search 'schemaName:"AWS EC2 Instance"'

For a single session (Windows Command Prompt):

cmd

REM Set for current cmd session
set SI_API_TOKEN=your_token_here

REM Now all commands work without the prefix
si whoami
si schema pull "*"
si component search "schemaName:\"AWS EC2 Instance\""

Permanently in your shell profile (Linux/macOS):

bash

# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish
echo 'export SI_API_TOKEN=your_token_here' >> ~/.bashrc
source ~/.bashrc

Permanently (Windows PowerShell):

powershell

# Set permanently for current user
[Environment]::SetEnvironmentVariable("SI_API_TOKEN", "your_token_here", [EnvironmentVariableTarget]::User)

# Restart PowerShell for changes to take effect

Permanently (Windows Command Prompt):

cmd

REM Set permanently for current user
setx SI_API_TOKEN "your_token_here"

REM Restart Command Prompt for changes to take effect

For multiple workspaces:

If you work with multiple workspaces, consider using direnv (Linux/macOS) or similar tools to set different tokens per project directory.

TIP

Like the --root option, the SI_ROOT environment variable is rarely needed. The CLI automatically discovers your project root by searching upward for .siroot.

Commands

TIP

Authentication Required Most commands below require the SI_API_TOKEN environment variable to be set. See the Setting Up Authentication section above for details on how to configure this.

`whoami` - Verify Authentication

Displays authenticated user information.

Usage

bash

si whoami

Example

bash

# Check authentication status
si whoami

`completion` - Generate Shell Completions

Generate shell completion scripts for bash, fish, or zsh.

Usage

bash

si completion <shell>

Available Shells

bash - Generate completions for bash
fish - Generate completions for fish
zsh - Generate completions for zsh

Examples

bash

# Bash completion
si completion bash > ~/.si-completion.bash
echo "source ~/.si-completion.bash" >> ~/.bashrc

# Zsh completion
si completion zsh > ~/.si-completion.zsh
echo "source ~/.si-completion.zsh" >> ~/.zshrc

# Fish completion
si completion fish > ~/.config/fish/completions/si.fish

AI Agent Integration

The si CLI includes a bundled AI Agent (MCP server) that integrates System Initiative with AI coding tools like Claude Code through the Model Context Protocol (MCP).

Quick Start

bash

# One-time setup
cd /path/to/your/project
si ai-agent init

# Daily use - just one command!
si ai-agent start
# → Launches Claude Code
# → Claude reads .mcp.json and starts bundled MCP server
# → Exit Claude when done (everything stops automatically)

`ai-agent init` - Initialize AI Agent

One-time setup: configure token and create MCP files.

Usage

bash

si ai-agent init [OPTIONS]

Options

Option	Type	Description	Default
`--target-dir <path>`	string	Directory to create config files	Current directory
`--api-token <token>`	string	System Initiative API token	Prompts if not provided
`--tool <name>`	string	AI tool: `claude`	`claude`

What It Does

Prompts for your System Initiative API token
Creates .mcp.json in your project (MCP server configuration)
Creates .claude/settings.local.json if using Claude Code

Getting Your API Token

Visit auth.systeminit.com/workspaces
Click the gear icon for your workspace
Select "API Tokens"
Generate a new token
Copy and paste when prompted

Examples

bash

# Interactive setup (prompts for token)
cd /path/to/your/project
si ai-agent init

# Provide token via flag - this will skip the user being prompted for the token
si ai-agent init --api-token eyJhbGc...

# Specify target directory
si ai-agent init --target-dir /path/to/project

# Use different AI tool
si ai-agent init --tool cursor

`ai-agent start` - Launch AI Tool

Launch Claude Code (which automatically starts the bundled MCP server).

Usage

bash

si ai-agent start [OPTIONS]

Options

Option	Type	Description	Default
`--tool <name>`	string	AI tool to launch	`claude`

Examples

bash

# Launch Claude Code (default)
si ai-agent start

# Launch specific tool
si ai-agent start --tool claude

`ai-agent config` - Manage Configuration

View or update AI agent configuration.

Usage

bash

si ai-agent config [OPTIONS]

Options

Option	Type	Description
`--show`	flag	Show current configuration (default)
`--update-token`	flag	Update the API token
`--tool <name>`	string	Update AI tool: `claude`

Examples

bash

# Show current configuration
si ai-agent config
si ai-agent config --show

# Update API token
si ai-agent config --update-token

`ai-agent stdio` - Run MCP Server

Run MCP server in stdio mode (for external AI tools to connect).

This command runs the MCP server in stdio mode, which is used internally by AI tools that read the .mcp.json configuration. You typically don't need to run this manually - use si ai-agent start instead.

Usage

bash

si ai-agent stdio

Example

bash

# Run MCP server in stdio mode
si ai-agent stdio

Schema Management

Manage schemas: initialize projects, generate functions locally, pull from and push to remote workspaces.

`schema init` - Initialize Project

Initialize a new System Initiative project by creating a .siroot marker file.

Usage

bash

si schema init [ROOT_PATH]

Arguments

Argument	Type	Description	Default
`ROOT_PATH`	string	Directory to initialize	Current directory

What It Does

Creates a .siroot marker file in the specified directory (or current directory if not specified). This marker file identifies the project root and enables the CLI to automatically discover your project from any subdirectory.

TIP

After initializing, you can run si commands from anywhere within your project. The CLI will automatically find the .siroot file by searching upward through parent directories.

Examples

bash

# Initialize in current directory (most common)
cd /path/to/my-project
si schema init

# Initialize a specific directory
si schema init /path/to/project

# After initialization, these both work from anywhere in the project:
cd /path/to/my-project/schemas/AWS::EC2::Instance
si schema generate action "AWS::EC2::Instance" create  # ← Works!

cd /path/to/my-project
si schema generate action "AWS::EC2::Instance" create  # ← Also works!

`schema generate scaffold` - Scaffold Complete Schema

Scaffolds a complete schema with all default functions and metadata.

Usage

bash

si schema generate scaffold [SCHEMA_NAME]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Name of the schema to scaffold

What It Creates

schemas/
└── <schema-name>/
    ├── .format-version
    ├── schema.ts
    ├── schema.metadata.json
    ├── actions/
    │   ├── create.ts
    │   ├── create.metadata.json
    │   ├── destroy.ts
    │   ├── destroy.metadata.json
    │   ├── refresh.ts
    │   ├── refresh.metadata.json
    │   ├── update.ts
    │   └── update.metadata.json
    ├── codeGenerators/
    ├── management/
    └── qualifications/

Examples

bash

# Scaffold a new schema
si schema generate scaffold "AWS::EC2::Instance"

# Scaffold with explicit root
si --root /path/to/project schema generate scaffold "AWS::EC2::SecurityGroup"

`schema generate action` - Generate Action Functions

Generates action functions (create, destroy, refresh, update) for schemas.

Usage

bash

si schema generate action [SCHEMA_NAME] [ACTION_NAME]

Arguments

Argument	Type	Description	Options
`SCHEMA_NAME`	string	Name of the schema	-
`ACTION_NAME`	string	Name of the action	`create`, `destroy`, `refresh`, `update`

Examples

bash

# Generate a create action
si schema generate action "AWS::EC2::Instance" create

# Generate all action functions
si schema generate action "AWS::EC2::Instance" create
si schema generate action "AWS::EC2::Instance" destroy
si schema generate action "AWS::EC2::Instance" refresh
si schema generate action "AWS::EC2::Instance" update

`schema generate authentication` - Generate Authentication Functions

Generates authentication functions for schemas.

Usage

bash

si schema generate authentication [SCHEMA_NAME] [AUTH_NAME]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Name of the schema
`AUTH_NAME`	string	Name of the authentication function

Examples

bash

# Generate an authentication function
si schema generate authentication "AWS Credential" validate-credentials

# Generate OAuth authentication
si schema generate authentication "GitHub Credential" oauth2

`schema generate codegen` - Generate Code Generator Functions

Generates code generator functions for schemas.

Usage

bash

si schema generate codegen [SCHEMA_NAME] [CODEGEN_NAME]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Name of the schema
`CODEGEN_NAME`	string	Name of the code generator

Examples

bash

# Generate a Terraform code generator
si schema generate codegen "AWS::EC2::Instance" terraform

# Generate a CloudFormation code generator
si schema generate codegen "AWS::EC2::VPC" cloudformation

# Generate a Pulumi code generator
si schema generate codegen "AWS::EC2::SecurityGroup" pulumi

`schema generate management` - Generate Management Functions

Generates management functions for schemas.

Usage

bash

si schema generate management [SCHEMA_NAME] [MANAGEMENT_NAME]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Name of the schema
`MANAGEMENT_NAME`	string	Name of the management function

Examples

bash

# Generate a reconcile function
si schema generate management "AWS::EC2::Instance" reconcile

# Generate a status check function
si schema generate management "AWS::EC2::Instance" check-status

`schema generate qualification` - Generate Qualification Functions

Generates qualification functions for schemas.

Usage

bash

si schema generate qualification [SCHEMA_NAME] [QUALIFICATION_NAME]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Name of the schema
`QUALIFICATION_NAME`	string	Name of the qualification function

Examples

bash

# Generate a validation qualification
si schema generate qualification "AWS::EC2::SecurityGroup" validate

# Generate a compliance check qualification
si schema generate qualification "AWS::EC2::SecurityGroup" compliance-check

`schema pull` - Pull from Remote

Pulls schemas from your remote System Initiative workspace.

Usage

bash

si schema pull [SCHEMA_NAME...]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Schema names to pull (supports wildcards)

Options

Option	Type	Description	Default
`--builtins`	flag	Include builtin schemas	Skipped by default

Wildcard Patterns

* - Pull all schemas
AWS::* - Pull all AWS schemas
Fastly::* - Pull all Fastly schemas

Examples

bash

# Pull a specific schema
si schema pull "AWS::EC2::Instance"

# Pull multiple schemas
si schema pull "AWS::EC2::Instance" "AWS::EC2::VPC" "AWS::EC2::Subnet"

# Pull all schemas in a category
si schema pull "AWS::EC2::*"

# Pull all schemas
si schema pull "*"

# Include builtin schemas
si schema pull --builtins "*"

`schema push` - Push to Remote

Pushes schemas to your remote System Initiative workspace.

Usage

bash

si schema push [SCHEMA_NAME...]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Schema names to push

Options

Option	Type	Description	Default
`-s, --skip-confirmation`	flag	Skip confirmation prompt	Shows prompt
`-b, --update-builtins`	flag	Change builtin schemas (SI Admin Only)	-

Examples

bash

# Push all schemas (prompts for confirmation)
si schema push

# Push specific schema
si schema push "AWS::EC2::Instance"

# Push multiple schemas
si schema push "AWS::EC2::Instance" "AWS::EC2::VPC" "AWS::EC2::Subnet"

# Skip confirmation prompt
si schema push --skip-confirmation

# Admin: Update builtin schemas
si schema push --update-builtins "AWS::EC2::Instance"

Schema Overlays

Manage schema overlays: generate overlay functions and push them to remote workspaces. Overlays allow you to customize or extend existing schemas without modifying the original schema definition.

`schema overlay generate` - Generate Overlay Functions

Generate overlay function definitions that customize or extend existing schemas.

Subcommands

action - Generate action overlay functions
authentication - Generate authentication overlay functions
codegen - Generate codegen overlay functions
management - Generate management overlay functions
qualification - Generate qualification overlay functions

Examples

bash

# Generate action overlay
si schema overlay generate action "AWS::EC2::Instance" custom-terminate

# Generate authentication overlay
si schema overlay generate authentication "AWS Credential" custom-auth

# Generate codegen overlay
si schema overlay generate codegen "AWS::EC2::Instance" custom-terraform

`schema overlay push` - Push Overlays

Pushes overlay funcs to your remote System Initiative workspace.

Usage

bash

si schema overlay push [SCHEMA_NAME...]

Arguments

Argument	Type	Description
`SCHEMA_NAME`	string	Schema names (overlays) to push

Examples

bash

# Push specific overlay
si schema overlay push "AWS::EC2::Instance"

# Push multiple overlays
si schema overlay push "AWS::EC2::Instance" "AWS::EC2::VPC" "AWS::EC2::SecurityGroup"

# Push all overlays (if no schema names specified)
si schema overlay push

Component Operations

Component-related operations: get, update, delete, and search components.

`component get` - Get Component

Get component data by name or ID.

Usage

bash

si component get <component> [OPTIONS]

Arguments

Argument	Type	Description
`component`	string	Component name or ID

Options

Option	Type	Description	Default
`-c, --change-set <id>`	string	Change set ID or name	`HEAD`
`-o, --output <format>`	string	Output format: `info`, `json`, or `yaml`	`info`
`--cache <file>`	string	Cache output to file (format from extension)	-
`--raw`	flag	Output raw API response as JSON	-

Environment Variables

SI_API_TOKEN (required)
SI_BASE_URL

Examples

bash

# Get component info
si component get my-server

# Output as JSON
si component get my-server --output json

# Output as YAML and cache to file
si component get my-server --output yaml --cache server.yaml

# Get from specific change set
si component get my-server --change-set dev

# Get raw API response
si component get my-server --raw

`component update` - Update Component

Update a component from JSON/YAML file (idempotent).

Usage

bash

si component update <input-file> --change-set <id-or-name> [OPTIONS]

Arguments

Argument	Type	Description
`input-file`	string	Path to input file (JSON or YAML)

Options

Option	Type	Description	Required
`-c, --change-set <id-or-name>`	string	Change set ID or name	Yes
`--component <id-or-name>`	string	Override component ID from file	No
`--dry-run`	flag	Show diff without applying changes	No

Environment Variables

SI_API_TOKEN (required)
SI_BASE_URL

Workflow: Get → Edit → Update

bash

# 1. Get current component state
si component get my-server --cache server.yaml

# 2. Edit server.yaml with your changes
vim server.yaml

# 3. Preview changes
si component update server.yaml --change-set dev --dry-run

# 4. Apply updates
si component update server.yaml --change-set dev

Examples

bash

# Update component from YAML file
si component update server.yaml --change-set dev

# Update with component ID override
si component update config.json --change-set dev --component my-server-id

# Preview changes first
si component update server.yaml --change-set dev --dry-run

`component delete` - Delete Component

Delete a component by name or ID.

Usage

bash

si component delete <component> --change-set <id-or-name> [OPTIONS]

Arguments

Argument	Type	Description
`component`	string	Component name or ID

Options

Option	Type	Description	Required
`-c, --change-set <id-or-name>`	string	Change set ID or name	Yes
`--dry-run`	flag	Preview deletion without applying	No

Environment Variables

SI_API_TOKEN (required)
SI_BASE_URL

Examples

bash

# Delete a component
si component delete my-server --change-set dev

# Preview deletion first
si component delete my-server --change-set dev --dry-run

# Delete by component ID
si component delete comp_1234567890 --change-set dev

`component search` - Search Components

Search for components using a search query.

Usage

bash

si component search <query> [OPTIONS]

Arguments

Argument	Type	Description
`query`	string	Search query

Options

Option	Type	Description	Default
`-c, --change-set <id>`	string	Change set ID or name	`HEAD`
`-o, --output <format>`	string	Output format: `info`, `json`, or `yaml`	`info`
`-a, --attribute <path>`	string	Include specific attribute paths (repeatable)	-
`--full-component`	flag	Show full component details	-

Environment Variables

SI_API_TOKEN (required)
SI_BASE_URL

Search Query Syntax

schemaName:"Schema Name"     - Search by schema name
tag:"tag-name"               - Search by tag
AND                          - Combine conditions
OR                           - Alternative conditions

Examples

bash

# Search by schema
si component search 'schemaName:"AWS EC2 Instance"'

# Search with tags
si component search 'tag:"production" AND tag:"web"'

# Search with specific attributes
si component search 'schemaName:"RDS Database"' \
  --attribute /domain/endpoint \
  --attribute /domain/port

# Get full component details
si component search 'tag:"production"' --full-component

# Output as JSON
si component search 'schemaName:"S3 Bucket"' --output json

Template Execution

Run infrastructure-as-code templates with convergence and idempotency.

`template run` - Run Template

Run a SI template file.

Usage

bash

si template run <template> --key <invocationKey> [OPTIONS]

Arguments

Argument	Type	Description
`template`	string	Path to template file

Options

Option	Type	Description	Required
`-k, --key <invocationKey>`	string	Invocation key (for idempotency)	Yes
`-i, --input <file>`	string	Input data file (JSON or YAML)	No
`-b, --baseline <file>`	string	Baseline data file (JSON or YAML)	No
`-c, --cache-baseline <file>`	string	Cache baseline results to file	No
`--cache-baseline-only`	flag	Exit after writing baseline cache	No
`--dry-run`	flag	Show planned changes without executing	No

Environment Variables

SI_API_TOKEN (required)
SI_BASE_URL (required)

Examples

bash

# Run a template
si template run ./templates/infrastructure.ts --key prod-deploy-001

# Run with input data
si template run ./templates/infra.ts \
  --key deploy-002 \
  --input ./inputs/production.yaml

# Run with baseline
si template run ./templates/infra.ts \
  --key deploy-003 \
  --baseline ./baselines/current.yaml

# Preview changes (dry run)
si template run ./templates/infra.ts \
  --key deploy-004 \
  --dry-run

# Cache baseline results
si template run ./templates/infra.ts \
  --key deploy-005 \
  --cache-baseline ./baselines/new-baseline.yaml

# Cache baseline and exit (no execution)
si template run ./templates/infra.ts \
  --key deploy-006 \
  --cache-baseline ./baselines/baseline.yaml \
  --cache-baseline-only

Writing Templates

Templates are TypeScript files that export a default function.

Template Structure

typescript

import { TemplateContext } from "../src/template.ts";
import { z } from "zod";

export default async function (ctx: TemplateContext) {
  // Set template name and change set
  ctx.name("my-infrastructure");
  ctx.changeSet("production");

  // Set search strings to find components
  ctx.search(["schema:AWS EC2 Instance", "tag:production"]);

  // Define input schema with defaults
  ctx.inputs(
    z.object({
      environment: z.string().default("production"),
      replicas: z.number().default(3),
    }),
  );

  // Transform the working set
  ctx.transform((workingSet) => {
    return workingSet.filter((c) => c.name.startsWith("prod-"));
  });

  // Use the logger
  ctx.logger.info("Template executing");
}

Template Context API

`ctx.name(name: string)`

Sets the template name.

typescript

ctx.name("production-infrastructure");

`ctx.changeSet(changeSet: string)`

Sets the change set to operate on.

typescript

ctx.changeSet("production");

`ctx.search(queries: string[])`

Sets search strings to find components.

typescript

ctx.search(["schema:AWS EC2 Instance", "tag:production", "tag:web"]);

`ctx.inputs(schema: ZodSchema)`

Defines input schema with validation and defaults.

typescript

ctx.inputs(
  z.object({
    environment: z.string().default("production"),
    instanceType: z.string().default("t3.medium"),
    replicas: z.number().min(1).max(10).default(3),
  }),
);

`ctx.transform(fn: Function)`

Transforms the working set of components.

typescript

ctx.transform((workingSet) => {
  return workingSet
    .filter((c) => c.name.startsWith("prod-"))
    .map((c) => ({
      ...c,
      tags: [...c.tags, "processed"],
    }));
});

`ctx.logger`

Logger instance for template output.

typescript

ctx.logger.info("Starting template execution");
ctx.logger.warn("Warning message");
ctx.logger.error("Error message");
ctx.logger.debug("Debug message");

Project Structure

SI projects follow this directory structure:

project-root/
├── .siroot                           # Marker file identifying project root
├── .mcp.json                         # MCP server configuration (if using AI agent)
├── .claude/                          # Claude-specific settings (if using Claude)
│   └── settings.local.json
└── schemas/                          # Schema definitions
    └── <schema-name>/
        ├── .format-version
        ├── schema.ts                 # Schema definition
        ├── schema.metadata.json      # Schema metadata
        ├── actions/                  # Action functions
        │   ├── create.ts
        │   ├── create.metadata.json
        │   ├── destroy.ts
        │   ├── destroy.metadata.json
        │   ├── refresh.ts
        │   ├── refresh.metadata.json
        │   ├── update.ts
        │   └── update.metadata.json
        ├── codeGenerators/           # Code generator functions
        │   ├── <codegen-name>.ts
        │   └── <codegen-name>.metadata.json
        ├── management/               # Management functions
        │   ├── <management-name>.ts
        │   └── <management-name>.metadata.json
        └── qualifications/           # Qualification functions
            ├── <qualification-name>.ts
            └── <qualification-name>.metadata.json

Common Workflows

Remember: after running si schema init, you can run si commands from

anywhere inside your project. The CLI automatically finds your project root!

Setting Up a New Project

bash

# 1. Initialize project (creates .siroot)
cd /path/to/project
si schema init

# 2. Set up AI agent
si ai-agent init

# 3. Create your first schema
si schema generate scaffold "AWS::EC2::Instance"

# 4. Now you can work from any subdirectory!
cd schemas/AWS::EC2::Instance
si schema generate action "AWS::EC2::Instance" create  # ← Works from here!

# 5. Start coding with AI
si ai-agent start

Working with Existing Schemas

bash

# 1. Pull schemas from workspace
si schema pull "*"

# 2. Make changes locally
# ... edit files ...

# 3. Push changes back
si schema push --skip-confirmation

Managing Components

bash

# 1. Search for components
si component search 'schemaName:"AWS EC2 Instance"'

# 2. Get component details
si component get my-server --cache server.yaml

# 3. Modify component
vim server.yaml

# 4. Update component
si component update server.yaml --change-set dev

Running Templates

bash

# 1. Write template
cat > infrastructure.ts << 'EOF'
import { TemplateContext } from "../src/template.ts";

export default async function (ctx: TemplateContext) {
  ctx.name("my-infrastructure");
  ctx.changeSet("production");
  ctx.search(["schema:AWS EC2 Instance"]);
}
EOF

# 2. Run template (dry run first)
si template run infrastructure.ts \
  --key deploy-001 \
  --dry-run

# 3. Run template for real
si template run infrastructure.ts --key deploy-001

Troubleshooting

Authentication Issues

If you encounter authentication errors:

Verify your SI_API_TOKEN is set correctly:
bash
```
echo $SI_API_TOKEN
```
Check token validity:
bash
```
si whoami
```

Ensure you're using the correct API endpoint:

bash

si --api-base-url https://api.systeminit.com whoami

Project Root Not Found

If the CLI reports it cannot find your project root (no .siroot file found), you have a few options:

Make sure you're in the right place:

bash

# Check if you're in or under a project directory
pwd
ls -la .siroot  # Should exist somewhere in your project

Initialize a new project if needed:

bash

# Create .siroot in the current directory
si schema init

Run from a different directory:

bash

# The CLI searches upward, so try from your actual project root
cd /path/to/project/root
si schema generate scaffold "AWS::EC2::Instance"

Explicitly specify the root (rare):

bash

# If you must run from outside the project
si --root /path/to/project schema generate scaffold "AWS::EC2::Instance"

The CLI searches upward from your current directory for .siroot.

This means:

✅ Works: /project/schemas/AWS::EC2::Instance/ → finds /project/.siroot
✅ Works: /project/ → finds /project/.siroot
❌ Fails: /some/other/directory/ → no .siroot found in parent directories

Verbose Logging

Enable verbose logging to debug issues:

bash

# Maximum verbosity (trace level)
si -v4 schema generate scaffold "AWS::EC2::Instance"

# Or specify numeric level (0-4)
si --verbose 4 template run template.ts --key test

AI Agent Issues

If the AI agent isn't working:

Check configuration:
bash
```
si ai-agent config --show
```
Verify .mcp.json exists:
bash
```
cat .mcp.json
```
Check MCP server directly:
bash
```
si ai-agent stdio
```
Update token if needed:
bash
```
si ai-agent config --update-token
```

SI CLI ​

Overview ​

Installation ​

Quick Install (Recommended) ​

Linux & macOS ​

Windows ​

Manual Installation ​

Global Options ​

Project Root Discovery ​

Verbosity Levels ​

Environment Variables ​

Setting Up Authentication ​

Commands ​

whoami - Verify Authentication ​

Usage ​

Example ​

completion - Generate Shell Completions ​

Usage ​

Available Shells ​

Examples ​

AI Agent Integration ​

Quick Start ​

ai-agent init - Initialize AI Agent ​

Usage ​

Options ​

What It Does ​

Getting Your API Token ​

Examples ​

ai-agent start - Launch AI Tool ​

Usage ​

Options ​

Examples ​

ai-agent config - Manage Configuration ​

Usage ​

Options ​

Examples ​

ai-agent stdio - Run MCP Server ​

Usage ​

Example ​

Schema Management ​

schema init - Initialize Project ​

Usage ​

Arguments ​

What It Does ​

Examples ​

schema generate scaffold - Scaffold Complete Schema ​

Usage ​

Arguments ​

What It Creates ​

Examples ​

schema generate action - Generate Action Functions ​

Usage ​

Arguments ​

Examples ​

schema generate authentication - Generate Authentication Functions ​

Usage ​

Arguments ​

Examples ​

schema generate codegen - Generate Code Generator Functions ​

Usage ​

Arguments ​

Examples ​

schema generate management - Generate Management Functions ​

Usage ​

Arguments ​

Examples ​

schema generate qualification - Generate Qualification Functions ​

Usage ​

Arguments ​

Examples ​

schema pull - Pull from Remote ​

Usage ​

Arguments ​

Options ​

Wildcard Patterns ​

Examples ​

schema push - Push to Remote ​

Usage ​

Arguments ​

Options ​

SI CLI

Overview

Installation

Quick Install (Recommended)

Linux & macOS

Windows

Manual Installation

Global Options

Project Root Discovery

Verbosity Levels

Environment Variables

Setting Up Authentication

Commands

`whoami` - Verify Authentication

Usage

Example

`completion` - Generate Shell Completions

Usage

Available Shells

Examples

AI Agent Integration

Quick Start

`ai-agent init` - Initialize AI Agent

Usage

Options

What It Does

Getting Your API Token

Examples

`ai-agent start` - Launch AI Tool

Usage

Options

Examples

`ai-agent config` - Manage Configuration

Usage

Options

Examples

`ai-agent stdio` - Run MCP Server

Usage

Example

Schema Management

`schema init` - Initialize Project

Usage

Arguments

What It Does

Examples

`schema generate scaffold` - Scaffold Complete Schema

Usage

Arguments

What It Creates

Examples

`schema generate action` - Generate Action Functions

Usage

Arguments

Examples

`schema generate authentication` - Generate Authentication Functions

Usage

Arguments

Examples

`schema generate codegen` - Generate Code Generator Functions

Usage

Arguments

Examples

`schema generate management` - Generate Management Functions

Usage

Arguments

Examples

`schema generate qualification` - Generate Qualification Functions

Usage

Arguments

Examples

`schema pull` - Pull from Remote

Usage

Arguments

Options

Wildcard Patterns

Examples

`schema push` - Push to Remote

Usage

Arguments

Options