Complete Command Reference

This page lists all available CLI commands with their flags and descriptions. For usage examples, see Commands Overview and Managing Simulations.

Configuration Priority

The CLI resolves configuration in this order:

1. Environment variables: SURESTAGE_BASE_URL, SURESTAGE_TOKEN, SURESTAGE_TENANT_SLUG
2. CLI flags: --base-url, --token, --tenant
3. Config file: ~/.surestage/config.yaml

Global Flags

All commands support these flags:

Flag	Description
--format json|table|yaml	Output format (default: table)
--no-color	Disable colored output
--verbose	Enable debug logging
--api-url	Override API endpoint
--base-url	API base URL
--token	Authentication token
--tenant	Tenant slug

auth

Authentication and tenant management.

Command	Description	Flags
auth login	Log in to SureStage	--email, --password
auth logout	Log out and clear credentials
auth status	Show current authentication status
auth refresh	Refresh JWT token
auth tenants	List available tenants
auth switch-tenant	Switch to a different tenant	--slug

instances

Sandbox simulation management.

Command	Description	Flags
instances list	List all simulations	--status active|stopped
instances create	Create a new simulation	--name, --description, --protocol http|graphql|grpc|websocket
instances start	Start a stopped simulation	--id, --name
instances stop	Stop a running simulation	--id, --name
instances reset	Reset simulation state to initial	--id, --name
instances delete	Delete a simulation	--id, --name, --force
instances url	Get simulation URL	--id, --name
instances logs	View simulation logs	--id, --name, --follow, --tail
instances import	Import simulation from file	--file, --format json|yaml
instances export	Export simulation to file	--id, --name, --output, --format json|yaml

routes

Route configuration for simulations.

Command	Description	Flags
routes list	List routes in a simulation	--instance-id, --method GET|POST|PUT|DELETE|PATCH
routes create	Create a new route	--instance-id, --method, --path, --response-id, --status-code
routes update	Update an existing route	--id, --method, --path, --response-id, --status-code
routes delete	Delete a route	--id, --force
routes import	Import routes from file	--instance-id, --file, --format json|yaml
routes export	Export routes to file	--instance-id, --output, --format json|yaml

responses

Response templates for routes.

Command	Description	Flags
responses list	List available responses	--instance-id
responses create	Create a response template	--instance-id, --name, --body, --status-code, --headers
responses update	Update a response template	--id, --name, --body, --status-code, --headers
responses delete	Delete a response template	--id, --force

collections

Reusable route environments.

Command	Description	Flags
collections list	List environments	--published
collections create	Create an environment	--name, --description, --routes
collections update	Update an environment	--id, --name, --description, --routes
collections delete	Delete an environment	--id, --force
collections publish	Publish an environment	--id, --visibility public|private|tenant

flows

Test flows and automation.

Command	Description	Flags
flows list	List all flows	--instance-id
flows create	Create a new flow	--name, --description, --steps
flows run	Execute a flow	--id, --variables
flows delete	Delete a flow	--id, --force

proxy

Proxy configuration for record and replay.

Command	Description	Flags
proxy list	List proxy configs	--instance-id
proxy create	Create a proxy config	--instance-id, --target-url, --mode record|replay|passthrough
proxy update	Update a proxy config	--id, --target-url, --mode
proxy delete	Delete a proxy config	--id, --force

ai

AI-powered mock generation and assistance.

Command	Description	Flags
ai generate-route	Generate route from description	--instance-id, --prompt, --method, --path
ai generate-response	Generate response from schema	--instance-id, --schema, --format json|xml
ai suggest-routes	Suggest routes for an API	--instance-id, --api-name, --api-type REST|GraphQL|gRPC

audit

Audit log access.

Command	Description	Flags
audit list	List audit events	--start-date, --end-date, --resource-type, --user-id

search

Global resource search.

Command	Description	Flags
search	Search across resources	--query, --resource-type instance|route|environment|flow

mockstate

Mock state management for stateful scenarios.

Command	Description	Flags
mockstate get	Get current state	--instance-id, --key
mockstate set	Set state value	--instance-id, --key, --value
mockstate reset	Reset state to initial	--instance-id

roles

Role management (admin only).

Command	Description	Flags
roles list	List all roles

rbac

Role-based access control assignments (admin only).

Command	Description	Flags
rbac list	List RBAC assignments	--user-id, --role-id
rbac assign	Assign role to user	--user-id, --role-id
rbac revoke	Revoke role from user	--user-id, --role-id

permissions

Permission definitions (admin only).

Command	Description	Flags
permissions list	List all permissions

users

User management (admin only).

Command	Description	Flags
users list	List users	--status active|inactive
users get	Get user details	--id, --email

memberships

Tenant membership management.

Command	Description	Flags
memberships list	List tenant members
memberships invite	Invite user to tenant	--email, --role
memberships remove	Remove user from tenant	--user-id

companies

Company (tenant) management.

Command	Description	Flags
companies list	List companies
companies get	Get company details	--id, --slug
companies update	Update company info	--id, --name, --slug

licenses

License and subscription information.

Command	Description	Flags
licenses list	List licenses
licenses get	Get license details	--id

featureflags

Feature flag management.

Command	Description	Flags
featureflags list	List feature flags	--enabled
featureflags get	Get flag status	--key
featureflags update	Update flag value	--key, --enabled true|false

compliance

Compliance policy management.

Command	Description	Flags
compliance list	List compliance policies
compliance create	Create a policy	--name, --type GDPR|HIPAA|SOC2, --rules
compliance update	Update a policy	--id, --name, --rules

preferences

User preferences.

Command	Description	Flags
preferences get	Get user preferences
preferences update	Update preferences	--timezone, --theme light|dark, --notifications

templates

Template deployment and management.

Command	Description	Flags
templates list	List available templates	--category
templates get	Get template details	--id, --slug
templates deploy	Deploy template to simulation	--template-id, --instance-id

systems

Global blueprint definitions.

Command	Description	Flags
systems list	List global blueprints
systems get	Get blueprint details	--id, --name

library

Blueprint library browsing.

Command	Description	Flags
library	Browse blueprint library	--category, --search

globalsystems

Global blueprint template management (admin only).

Command	Description	Flags
globalsystems list	List global templates
globalsystems create	Create global template	--name, --description, --config
globalsystems update	Update global template	--id, --name, --description, --config
globalsystems delete	Delete global template	--id, --force

tasks

Task execution and management.

Command	Description	Flags
tasks list	List tasks	--status pending|running|complete|failed
tasks get	Get task details	--id
tasks create	Create a new task	--type, --config
tasks execute	Execute a task	--id

tours

Product tour progress tracking.

Command	Description	Flags
tours list	List available tours
tours get	Get tour details	--id
tours progress	Get tour progress	--id

tui

Interactive terminal UI mode.

Command	Description	Flags
tui	Launch terminal UI

version

Version information.

Command	Description	Flags
version	Show CLI version

config

CLI configuration management.

Command	Description	Flags
config init	Initialize config file	--path
config show	Show current config

Examples

Basic Workflow

# Authenticate
surestage auth login --email you@example.com

# List tenants and switch
surestage auth tenants
surestage auth switch-tenant --slug your-tenant

# Create and start simulation
surestage instances create --name "My API" --protocol http
surestage instances start --name "My API"

# Get simulation URL
surestage instances url --name "My API"

Export and Import

# Export simulation config
surestage instances export --name "My API" --output ./my-api.json

# Import into another tenant
surestage auth switch-tenant --slug another-tenant
surestage instances import --file ./my-api.json

Working with JSON Output

# Get JSON output for scripting
surestage instances list --format json | jq '.[] | select(.status == "active")'

# Set state programmatically
surestage mockstate set --instance-id abc123 --key "user_id" --value "12345"

Related

• Commands Overview - Command categories and basics
• Managing Simulations - Simulation operation guide
• Working with Routes - Route configuration guide
• Authentication - Auth setup and troubleshooting