@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 reloads registry credentials once and replays the request once
• 401 errors — failures identify the selected instance, request hostname, workspace, and registry identity without exposing credentials

Custom-domain identity and request routing remain separate: commands try the requested hostname first and only use a discovered .xano.io CNAME after a transport failure. DNS aliases never overwrite the saved instance or silently select another registry credential.

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 resolves the target's workspace-inventory name and description, then reports duration percentiles (avg, p50, p95, p99), ancestry, flat hotspots, functions_called, and high-confidence issues. ancestry keeps each step's full static/runtime path and parent contribution. hotspots groups by _xsid; its pct_of_total is based on exclusive/direct time, so the percentages remain additive instead of double-counting inclusive parent time. Inclusive rollups are retained separately for drill-down.

occurrences and total_invocations count stack nodes actually retained in the fetched payloads; they are not execution multipliers. When any stack is capped, truncated_samples is nonzero and occurrences_complete/calls_complete are false, so those counts are explicitly lower bounds. Loop nodes separately expose Xano's runtime_count_total and iterations_total without multiplying already-unrolled child nodes.

Function identity is resolved from raw.context.function.id when Xano supplies it, otherwise from an exact and unambiguous _xsid match in a target/function static definition whose update timestamp is no newer than the execution. Names, titles, and current definitions changed after a historical execution are never treated as authoritative identifiers. A missing, ambiguous, or non-version-aligned match remains in functions_called with identity.status: unresolved and a reason. Function time is inclusive; each record reports calls/request, seconds/call, percentage of the sampled target's request time, and caller_scope: single_target. It does not claim callers outside the traced target.

Deep-dive expands a single request's stack into a recursive tree. Runtime timing is an inclusive rollup; direct_seconds subtracts child rollups and clamps only negative clock/rounding residue. Runtime coordinates (position2, then position) are preferred, with deterministic tree positions as a fallback because live payloads may omit both. Each node keeps Xano's type-specific runtime_count, the number of retained_stack_nodes, and (for loop nodes only) iterations. Function call_count counts retained invocation nodes rather than treating a function node's cnt as calls.

Warnings and trace issues identify slow steps inside loops (N+1 queries, lambda blocks, external API calls) with an evidence path and concrete suggestion. A #ignore-performance marker or explicit suppression flag in available runtime/static metadata suppresses the warning for that subtree, and task traces opt out globally. Current task history commonly returns duration without retained stack data; in that case trace can report target metadata and duration percentiles but ancestry, hotspots, functions, and issues are empty. When Xano omits suppression metadata, the CLI cannot infer an author-side suppression and reports the runtime warning. See the trace/deep-dive initiative for the broader command context; the fields documented here are the current runtime contract.

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

docs — Markdown Documentation (read-only)

Export human-readable Markdown for your workspace (same idea as the State Change extension’s documentation export): APIs with curl examples, function stacks, tasks, triggers, functions, and toolsets. Uses workspace sinks plus Xano XS metadata for step labels.

sc-xano docs workspace -o workspace.md              # Full workspace
sc-xano docs api --app-id <id> -o api-group.md      # One API group + endpoints
sc-xano docs endpoint --id <query-id>               # Single endpoint
sc-xano docs function --id <id>
sc-xano docs task --id <id>
sc-xano docs trigger --id <id>
sc-xano docs workspace --no-steps --no-internals    # Shorter output

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>

# Export every supported type into its own subdirectory
sc-xano xanoscript export-all --type all --output-dir ./backup

# Export only one concrete type
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

--type all attempts function, table, api, task, trigger, mcp_server, addon, and middleware, continuing after individual type or object failures. Both complete and concrete exports write beneath <output-dir>/<type>/, print per-type and aggregate retained/skipped/error totals, and exit nonzero if any export fails. Filenames are collision-safe: the first object keeps <sanitized-name>.xs; later collisions prefer <sanitized-name>_<id>.xs, then a deterministic numeric suffix when needed. The --type option remains required so a complete export is always deliberate. Existing files and case-only filename collisions are treated as claimed paths, so rerunning an export into the same directory preserves earlier output.

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.

Releasing

Maintainers publish deliberate GitHub Releases through npm trusted publishing; no long-lived npm write token is stored in GitHub. See the release runbook for versioning, the one-time npm binding, publication checks, and recovery.

License

MIT