Skip to content

CLI Commands Reference

Complete reference for the scs command-line interface.

Note: The CLI is primarily for bundle authoring (Phase 1). Deployment, agent management, and context requests are done via the REST API or gRPC.

Installation

cd cli
pip install -e .

Global Options

scs --version          # Show version
scs --help             # Show help
scs <command> --help   # Show command help

Project Management

scs new

Create a new SCS project with scaffolding.

scs new <project-name> --type <template-type>

Options: - --type - Template type: healthcare, fintech, saas, government, minimal, standard

Examples: 

scs new my-healthcare-project --type healthcare
scs new my-saas-app --type saas
scs new quick-test --type minimal

scs init

Initialize SCS in an existing project.

scs init

Creates .scs/ directory with default configuration.

Bundle Management

scs bundle create

Interactive bundle creation wizard.

scs bundle create

Prompts for: - Bundle type (meta, standards, domain, concern, project) - Bundle ID - Title and description - SCDs to include - Imports (if applicable)

Options: - --non-interactive - Use defaults, no prompts - --template <path> - Use specific template

scs bundle version

Version and lock a bundle (makes it immutable).

scs bundle version <bundle-path> --version <semver>

Examples: 

scs bundle version ./bundles/my-bundle.yaml --version 1.0.0
scs bundle version ./bundles/acme-security.yaml --version 2.1.0

Creates versioned file: bundle-<name>-<version>.yaml

scs validate

Validate bundle or SCD structure.

scs validate <file-path> [--strict]

Options: - --strict - Enforce strict validation (Phase 2) - Default: Loose validation (Phase 1)

Examples: 

# Validate bundle (loose)
scs validate ./bundles/my-bundle.yaml

# Validate bundle (strict - for versioning)
scs validate ./bundles/my-bundle.yaml --strict

# Validate SCD
python -m scs_validator ./scds/my-scd.yaml

SCD Management

python -m scs_validator

Validate SCD files.

python -m scs_validator <scd-path>

Example: 

python -m scs_validator ./scds/company-overview.yaml

Configuration

scs config

Manage SCS configuration.

# Show config
scs config show

# Set config value
scs config set <key> <value>

# Get config value
scs config get <key>

Example: 

scs config set api.endpoint http://localhost:8000
scs config set api.key sk_your_api_key

Utility Commands

scs info

Show SCS installation info.

scs info

Displays: - SCS version - Python version - Installation path - Configuration location

Examples

Complete Bundle Authoring Workflow

# 1. Create new project
scs new my-healthcare-app --type healthcare
cd my-healthcare-app

# 2. Create a concern bundle
scs bundle create
# ... follow prompts ...

# 3. Validate (loose)
scs validate ./bundles/my-concern.yaml

# 4. Make refinements, validate again
scs validate ./bundles/my-concern.yaml

# 5. Version when ready
scs bundle version ./bundles/my-concern.yaml --version 1.0.0

Publishing to Registry (via API)

After creating a bundle with the CLI, publish it via the API:

# Publish bundle to registry
curl -X POST http://localhost:8000/api/bundles \
  -H "Content-Type: application/json" \
  -d @bundle.json

Registering Agents (via API)

Agent management is done via the API, not CLI:

# Register agent
curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent:my-agent",
    "name": "My Agent",
    "role_id": "role:prior-auth-agent",
    "allowed_intents": ["prior_auth_check"]
  }'

# Generate API key
curl -X POST http://localhost:8000/api/agents/agent:my-agent/api-keys

Requesting Context (via API)

Context requests are done via REST API or gRPC:

# Request context
curl -X POST http://localhost:8000/api/context \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_your_api_key" \
  -d '{"task_type": "prior_auth_check"}'

Command Status

Command Status Notes
scs new ✅ Implemented Project scaffolding
scs init ✅ Implemented Initializes .scs directory
scs bundle create ✅ Implemented Interactive wizard
scs validate ✅ Implemented Loose and strict modes
scs bundle version ✅ Implemented Creates versioned bundle
scs config ✅ Implemented Configuration management
scs info ✅ Implemented Shows version info

CLI vs API

The CLI is designed for bundle authoring (Phase 1-2). Operations that involve the running system use the REST API or gRPC:

Operation Tool
Create bundles CLI (scs bundle create)
Validate bundles CLI (scs validate)
Version bundles CLI (scs bundle version)
Publish to registry API (POST /api/bundles)
Register agents API (POST /api/agents)
Generate API keys API (POST /api/agents/{id}/api-keys)
Request context API (POST /api/context) or gRPC
Manage tags API (POST /api/tags)

Next Steps