@statechange/xano-cli

CLI for Xano performance analysis, operational insights, and critical security and restart abilities. Provides capabilities offered in the State Change Extension for Xano.

Requirements

• A State Change subscription
• The State Change browser extension installed and having previously been active on your instance in Chrome (or a supported browser)

Getting Started with AI Agents

The fastest way to put this CLI to work is to install the skills into your AI coding agent:

npx skills add @statechange/xano-cli

This teaches your agent (Claude Code, Cursor, etc.) how to analyze performance bottlenecks, trace slow endpoints, audit security, and generate XanoScript — all through natural conversation.

Installation

npm install -g @statechange/xano-cli

Or run directly with npx (no install needed):

npx @statechange/xano-cli <command>

Quick Start

# 1. Authenticate via browser (opens automatically)
sc-xano auth login

# 2. Verify connection and see available instances
sc-xano auth whoami

# 3. Run commands (instance, workspace, and token auto-resolve)
sc-xano inventory workspace
sc-xano performance top-endpoints
sc-xano audit workspace

Once authenticated, the CLI auto-resolves your Xano instance, workspace, and token from the StateChange backend. No extra flags needed if you have a single instance.

Safety: Read-Only vs Write Commands

Most commands are read-only and safe to run without side effects. Four commands write to the Xano instance — confirm with the user before running these:

| Command | Effect | |---------|--------| | logs set | Changes history retention settings on endpoints, tasks, or triggers | | secure swagger | Modifies API app Swagger/documentation configuration | | health clear-history | Deletes history database tables on the instance | | health restart-tasks | Restarts the task service deployment |

All other commands are read-only.

Commands

auth — Authentication & Session Management

sc-xano auth login                       # Authenticate via browser (device code flow) — recommended
sc-xano auth init                        # Interactive API key setup (manual)
sc-xano auth init --api-key <key>        # Direct API key setup
sc-xano auth whoami                      # Verify auth and list instances
sc-xano auth status                      # Check Xano token health and session freshness
sc-xano auth set-instance <host>         # Save default instance
sc-xano auth set-instance <host> --workspace <id>  # Save default instance and workspace

Session Freshness

Your Xano session token is refreshed whenever you open Xano in the browser with the StateChange extension active. The CLI monitors token health automatically:

• Fresh token — commands run normally
• Stale token — a warning is shown, but commands still proceed
• Expired token — a warning is shown; if Xano rejects the request, the CLI prompts you to open Xano and polls until the session is refreshed
• 401/403 errors — the CLI advises running auth status to diagnose

performance — Performance Analysis (read-only)

Find slow endpoints, trace execution bottlenecks, and deep-dive into request stacks.

# Rank all endpoints/tasks/triggers by total server time
sc-xano performance top-endpoints                       # Last 24 hours
sc-xano performance top-endpoints --lookback 48         # Custom lookback (hours)
sc-xano performance top-endpoints --limit 10            # Limit results

# Trace: aggregate stack analysis across multiple executions
sc-xano performance trace endpoint <query-id>           # Endpoint trace
sc-xano performance trace task <task-id>                # Task trace
sc-xano performance trace trigger <trigger-id>          # Trigger trace
sc-xano performance trace endpoint <id> --samples 20   # Custom sample count

# Deep-dive: full stack expansion for a single request
sc-xano performance deep-dive <request-id>

# Scan all functions for nested slow steps
sc-xano performance scan-functions
sc-xano performance scan-functions --min-nesting 3      # Custom nesting threshold

Trace aggregates timing data across N samples, showing duration percentiles (avg, p50, p95, p99) and per-step breakdown by _xsid. Steps with high occurrences relative to samples indicate they run inside loops.

Deep-dive expands a single request's stack into a recursive tree with direct vs rollup timing, percentage breakdowns (pct_of_total, pct_of_parent), loop iteration counts, and warnings for slow steps inside loops (N+1 queries, lambda blocks, external API calls).

xray — Function Analysis (read-only)

Static analysis of function internals: step hierarchy, performance warnings, dependencies on other functions.

sc-xano xray function --id <function-id>        # Analyze a single function
sc-xano xray scan-workspace                      # Scan all functions for errors
sc-xano xray scan-workspace --include-warnings   # Include warnings (not just errors)

audit — Security Auditing (read-only)

Audit workspace objects for configuration issues, unsecured endpoints, and schema problems.

sc-xano audit workspace        # Audit all API group configurations
sc-xano audit swagger           # Find unsecured Swagger/documentation endpoints
sc-xano audit database          # Audit table schemas, indexes, and relationships
sc-xano audit middleware        # Audit middleware configurations
sc-xano audit addons            # Audit addon configurations
sc-xano audit tasks             # Audit background task configurations
sc-xano audit triggers          # Audit trigger configurations
sc-xano audit mcp-servers       # Audit MCP/toolset server configurations

secure — Security Management (WRITE)

Apply security changes to workspace objects. These commands modify your Xano instance.

sc-xano secure swagger --app-id <id> --disable           # Disable Swagger entirely
sc-xano secure swagger --app-id <id> --require-token      # Require token for Swagger access

history — Execution History (read-only)

Browse request, task, trigger, and MCP server execution history.

# API request history
sc-xano history requests                          # Recent requests (page 1)
sc-xano history requests --page 2                 # Paginate
sc-xano history request <request-id>              # Full request detail (stack, timing, I/O)

# Task history
sc-xano history tasks <task-id>                   # List task executions
sc-xano history task-run <task-id> <run-id>       # Detailed task run

# Trigger history
sc-xano history triggers <trigger-id>             # List trigger executions

# MCP server history
sc-xano history mcp-servers <tool-id>             # List MCP server executions

logs — Log Retention Management (show/watch read-only, set is WRITE)

View and control how much execution history Xano retains per endpoint, task, or trigger. Useful when performance deep-dives show stack_truncated: true. logs set modifies your Xano instance.

# View retention settings
sc-xano logs show                             # All objects' retention settings
sc-xano logs show --custom-only               # Only objects with non-default settings
sc-xano logs show endpoint <id>               # Single endpoint with parent app context
sc-xano logs show app <id>                    # App and all its child endpoints
sc-xano logs show task <id>                   # Single task
sc-xano logs show trigger <id>               # Single trigger

# Update retention
sc-xano logs set endpoint <id> --limit -1     # Unlimited (capture full stacks for debugging)
sc-xano logs set endpoint <id> --limit 100    # Default (top 100 stack steps)
sc-xano logs set endpoint <id> --limit 0      # Disable history retention
sc-xano logs set task <id> --limit -1         # Works for tasks too
sc-xano logs set trigger <id> --limit -1      # And triggers

# Watch for new executions in real-time
sc-xano logs watch endpoint <id>              # Poll and display new executions as they arrive

inventory — Workspace Overview (read-only)

List and count all objects in your workspace.

sc-xano inventory workspace           # Object counts summary
sc-xano inventory functions            # List all functions with tags
sc-xano inventory tables               # List all database tables
sc-xano inventory tasks                # List all background tasks
sc-xano inventory triggers             # List all triggers
sc-xano inventory addons               # List all addons
sc-xano inventory middleware           # List all middleware
sc-xano inventory mcp-servers          # List all MCP/toolset servers

xanoscript — XanoScript Generation (read-only)

Generate XanoScript source code from live Xano objects. Supports all object types.

# Generate XanoScript for a single object
sc-xano xanoscript generate function <id>
sc-xano xanoscript generate table <id>
sc-xano xanoscript generate api <id>
sc-xano xanoscript generate task <id>
sc-xano xanoscript generate trigger <id>
sc-xano xanoscript generate mcp_server <id>
sc-xano xanoscript generate addon <id>
sc-xano xanoscript generate middleware <id>

# Bulk export all objects of a type to .xs files
sc-xano xanoscript export-all --type function
sc-xano xanoscript export-all --type table
sc-xano xanoscript export-all --type api
sc-xano xanoscript export-all --type task
sc-xano xanoscript export-all --type trigger
sc-xano xanoscript export-all --type mcp_server
sc-xano xanoscript export-all --type addon
sc-xano xanoscript export-all --type middleware
sc-xano xanoscript export-all --type function --output-dir ./backup   # Custom output directory

health — Instance Health & Restarts (instances/database read-only, clear-history/restart-tasks WRITE)

Instance-level operations for monitoring and recovery. clear-history and restart-tasks modify your Xano instance.

sc-xano health instances                              # List all instances with status
sc-xano health database --instance-id <id>            # Show history database sizes
sc-xano health clear-history --instance-id <id>       # Clear history databases
sc-xano health clear-history --instance-id <id> --tables request_history,task_history  # Clear specific tables
sc-xano health restart-tasks --instance-id <id>       # Restart the task service deployment

flush — Cache Management

The CLI caches workspace data in-memory for 60 seconds. Use flush when you know data has changed externally.

sc-xano flush

Common Flags

These flags work on most commands but are usually auto-resolved:

| Flag | Environment Variable | Description | |------|---------------------|-------------| | --api-key <key> | STATECHANGE_API_KEY | StateChange API key | | --instance <host> | XANO_INSTANCE | Xano instance hostname | | --workspace <id> | XANO_WORKSPACE | Workspace ID | | --token <token> | XANO_TOKEN | Xano API token | | --branch <id> | — | Branch ID (default: 0) | | --format <fmt> | — | Output format: table (default), json, or yaml |

Use --format yaml when feeding output to an AI/LLM — it is the most token-efficient structured format.

License

MIT