Symulate Symulate

CLI Reference

Complete guide to Symulate's command-line interface

The Symulate CLI provides powerful commands for authentication, cache management, endpoint synchronization, and more. All commands are available via npx @symulate/sdk or the shorter alias npx symulate.

Quick Start

Get started with the CLI in three simple steps:

npx symulate login        # Authenticate with platform
npx symulate sync         # Sync your endpoints
npx symulate cache        # Inspect cached data

Authentication Commands

login

Authenticate with Symulate Platform to access cloud features like Supabase cache sync.

npx symulate login

How it works:

  1. Generates a session token and opens your browser
  2. You authenticate on the platform
  3. CLI receives your session and saves it locally
  4. You're ready to use cloud features!

Example Output:

[Symulate] Creating session...
[Symulate] Opening browser for authentication...
[Symulate] Waiting for authentication...
[Symulate] ✓ Successfully authenticated as user@example.com
[Symulate] ✓ Auto-selected organization and project

logout

Clear your Symulate Platform session and remove stored credentials.

npx symulate logout

whoami

Display information about the currently authenticated user.

npx symulate whoami

Example Output:

[Symulate] Current User:
  Email: user@example.com
  User ID: 550e8400-e29b-41d4-a716-446655440000
  Current Organization: acme-inc
  Current Project: default-project
  Expires: 1/25/2026, 3:45 PM

Organization Management

orgs list

List all organizations you belong to.

npx symulate orgs list

Example Output:

[Symulate] Your Organizations:

  Acme Inc (current)
    ID: org-550e8400-e29b-41d4-a716-446655440000
    Slug: acme-inc
    Role: owner

  Example Corp
    ID: org-7c9e6679-7425-40de-944b-e07fc1f90ae7
    Slug: example-corp
    Role: member

orgs use

Switch to a different organization. Accepts organization ID or slug.

npx symulate orgs use <org-identifier>

# Examples
npx symulate orgs use acme-inc
npx symulate orgs use org-550e8400-e29b-41d4-a716-446655440000

Parameters:

  • <org-identifier> - Organization ID or slug (required)

Project Management

projects list

List all projects in the current organization.

npx symulate projects list

Note: You must select an organization first using orgs use

projects use

Switch to a different project. Accepts project ID or slug.

npx symulate projects use <project-identifier>

# Examples
npx symulate projects use default-project
npx symulate projects use proj-abc123

Parameters:

  • <project-identifier> - Project ID or slug (required)

API Key Management

api-keys

List all API keys associated with your account.

npx symulate api-keys

Displays:

  • API key ID (for use with --key option)
  • Truncated key value (for security)
  • Key name (if set)
  • Status (Active/Revoked)
  • Creation and expiration dates

Endpoint Synchronization

sync

Synchronize local endpoint definitions to Symulate Platform.

npx symulate sync

How it works:

  1. Loads endpoint definitions from your project (via symulate.config.js)
  2. Fetches remote endpoints from the platform
  3. Compares local vs remote endpoints
  4. Detects potential conflicts (e.g., parameter renames)
  5. Prompts for conflict resolution
  6. Syncs changes to the platform

Example Output:

[Symulate] Syncing endpoints to project: proj-abc123

[Symulate] Found 10 local endpoint(s):
  • GET /api/users
  • POST /api/users
  • GET /api/users/:id
  ...

[Symulate] 📊 Sync Summary:
  • 2 endpoint(s) to create
  • 6 endpoint(s) to update
  • 0 endpoint(s) to delete

[Symulate] ✅ Sync completed successfully!

Requirements: Authentication, selected organization/project, and symulate.config.js file

Cache Management

cache

Inspect cached mock data from both local cache and Supabase.

npx symulate cache [options]

Options:

  • -l, --list - List all cached entries (default)
  • -h, --hash <hash> - Show details for a specific hash
  • -s, --search <pattern> - Search for entries matching pattern
  • -f, --full - Show full data instead of preview
  • --remote - Show only Supabase cache (requires login)
  • -k, --key <api-key> - Filter by API key ID

Examples:

# List all cached entries
npx symulate cache

# Show full data for a specific hash
npx symulate cache --hash abc123xyz

# Search for entries matching pattern
npx symulate cache --search users

# Show full data in search results
npx symulate cache --search products --full

# Show only Supabase cache
npx symulate cache --remote

# Filter by API key
npx symulate cache --key api_key_id_123

regenerate

Regenerate mock data by clearing the cache (both local and Supabase).

npx symulate regenerate [options]

Options:

  • -p, --preview - Preview cached endpoints without clearing
  • -h, --hash <hash> - Clear cache for a specific hash
  • -e, --endpoint <pattern> - Clear cache for endpoints matching pattern
  • -k, --key <api-key> - Filter by API key ID

Examples:

# Clear all cache (regenerates on next request)
npx symulate regenerate

# Preview what's cached without clearing
npx symulate regenerate --preview

# Clear specific cache entry by hash
npx symulate regenerate --hash abc123xyz

# Clear entries matching a pattern
npx symulate regenerate --endpoint users

# Regenerate for specific API key
npx symulate regenerate --key api_key_id_123

clear-cache

Clear the local cache file (legacy command).

npx symulate clear-cache [options]

Options:

  • -k, --key <api-key> - Filter by API key ID

Note: Consider using regenerate instead (more flexible)

OpenAPI Generation

openapi

Generate OpenAPI 3.0 specification from your endpoint definitions.

npx symulate openapi [options]

Options:

  • -o, --output <path> - Output file path (default: ./openapi.json)
  • -t, --title <title> - API title (default: Symulate Generated API)
  • -v, --version <version> - API version (default: 1.0.0)
  • -d, --description <description> - API description
  • -s, --server <url> - Server URL (e.g., https://api.example.com)

Examples:

# Basic usage - generates openapi.json
npx symulate openapi

# Specify output file
npx symulate openapi -o api-spec.json

# Full customization
npx symulate openapi \
  -o ./docs/api.json \
  -t "My API" \
  -v "2.0.0" \
  -d "API for My Application" \
  -s https://api.example.com

Generated specification includes:

  • Request/response schemas from your Symulate schemas
  • Path parameters (e.g., :id)
  • Request bodies for POST/PUT/PATCH
  • Tags for organization
  • Error responses (custom or default 400, 404, 500)

Custom Error Responses

Define custom error responses in your endpoints for more detailed OpenAPI specs:

export const getUser = defineEndpoint<User>({
  path: '/api/users/:id',
  method: 'GET',
  schema: UserSchema,
  errors: [
    {
      code: 404,
      description: 'User not found',
      schema: m.object({
        error: m.object({
          message: m.string(),
          code: m.string(),
        }),
      }),
    },
    {
      code: 403,
      description: 'Access denied',
      schema: m.object({
        error: m.object({
          message: m.string(),
        }),
      }),
    },
  ],
});

Note: If no errors array is provided, default error responses (400, 404, 500) with a standard error schema will be included in the OpenAPI spec.

Configuration

symulate.config.js

Most CLI commands require a configuration file to locate your endpoint definitions.

// symulate.config.js
export default {
  entries: [
    "./src/models/**/*.ts",      // TypeScript files
    "./server/api/**/*.js",      // JavaScript files
  ]
};

Framework-specific examples:

// Angular
export default {
  entries: ["./src/app/models/**/*.ts"]
};

// Nuxt
export default {
  entries: ["./server/api/**/*.ts"]
};

// Express
export default {
  entries: ["./src/routes/**/*.ts"]
};

// Built files
export default {
  entries: ["./dist/**/*.js"]
};

Common Workflows

Initial Setup

# Authenticate with platform
npx symulate login

# View your organizations
npx symulate orgs list

# Switch to an organization (if needed)
npx symulate orgs use acme-inc

# View projects in current org
npx symulate projects list

# Switch to a project (if needed)
npx symulate projects use default-project

# List your API keys
npx symulate api-keys

Development Workflow

# Sync local endpoints to platform
npx symulate sync

# Inspect cached data
npx symulate cache

# Regenerate mock data
npx symulate regenerate

# Generate OpenAPI spec for backend team
npx symulate openapi -o api-spec.json

Cache Management

# Preview what's cached
npx symulate regenerate --preview

# Clear specific endpoint cache
npx symulate regenerate --endpoint /api/users

# Search for specific cache entries
npx symulate cache --search products

# View full data for a hash
npx symulate cache --hash abc123xyz

Need Help?

Each command supports the --help flag for detailed usage information.

npx symulate --help
npx symulate cache --help
npx symulate openapi --help