Caly Xano CLI

Caly Xano CLI

Automate backups, docs, testing, and version control for Xano backends.

FIRST: Verify Installation

xano --version  # Requires v0.15.0+

If not installed:

pnpm install -g @calycode/cli
# or through your preferred package manager

Key Guidelines

• Initialize first: Run xano init before using any other commands. This sets up instance configuration.
• Context-aware: Most commands inherit --instance, --workspace, --branch from current context.
• Use --all flag: For bulk operations across all API groups in a workspace.
• OpenAPI-centric: Many commands generate or consume OpenAPI 3.1+ specifications.
• Non-destructive by default: Backup restore is the only destructive operation (requires explicit flags).

Quick Start: New Project

# Initialize with Xano instance (interactive)
xano init

# Or non-interactive setup
xano init --name my-instance --url https://x123.xano.io --token <METADATA_API_TOKEN> --directory ./my-project

Quick Reference: Core Commands

Initialization

Interactive Setup

xano init

Prompts for:

• Instance name (identifier for this config)
• Instance URL (e.g., https://x123.xano.io)
• Metadata API token (from Xano dashboard)
• Output directory

Non-Interactive Setup

xano init \
  --name production \
  --url https://x123.xano.io \
  --token <METADATA_API_TOKEN> \
  --directory ./xano-project

Options

OpenAPI Specification Generation

Generate for Single API Group

# Uses current context
xano generate spec

# Specify API group
xano generate spec --group "API Group Name"

# Include table schemas
xano generate spec --include-tables

Generate for All API Groups

xano generate spec --all

Options

Output

Generates OpenAPI 3.1+ spec with Scalar API Reference documentation.

Code Generation (SDK/Client)

Generate TypeScript Client

xano generate codegen --generator typescript-axios

Available Generators

Supports all OpenAPI Generator tools plus Orval clients:

# OpenAPI Generator (100+ generators)
xano generate codegen --generator typescript-axios
xano generate codegen --generator python
xano generate codegen --generator kotlin
xano generate codegen --generator swift5

# Orval clients (prefix with orval-)
xano generate codegen --generator orval-axios
xano generate codegen --generator orval-fetch
xano generate codegen --generator orval-react-query

Passthrough Arguments

# Pass additional args to generator
xano generate codegen --generator typescript-axios -- --additional-properties=supportsES6=true

Options

Documentation Generation

Generate Internal Docs

xano generate docs

Collects all descriptions and internal documentation from Xano instance into a static documentation suite.

Options

Repository Generation

Generate Repo Structure

xano generate repo

Processes Xano workspace into a repo structure with Xanoscripts (Xano 2.0+).

Options

Backups

Export Backup

xano backup export

Creates a full backup of workspace via Metadata API.

Restore Backup

xano backup restore --source-backup ./backup.json

WARNING: This is destructive! Overwrites all business logic and restores v1 branch. Data is also restored. Error-prone, this action might result with errors, that cannot be resolved without Support from Xano Team.

Options

API Testing

Run Test Suite

# Short form (recommended)
xano test run -c ./test-config.json

# Long form
xano test run --test-config-path ./test-config.json

Executes API tests based on test configuration file.

With Environment Variables

# Short form
xano test run -c ./test-config.json -e API_KEY=secret -e TEST_EMAIL=test@example.com

# Long form
xano test run \
  --test-config-path ./test-config.json \
  --test-env API_KEY=secret \
  --test-env BASE_URL=https://api.example.com

CI/CD Mode (Exit on Failure)

# Exit with code 1 if any tests fail
xano test run -c ./test-config.json --ci

# Also fail on warnings
xano test run -c ./test-config.json --ci --fail-on-warnings

Options

Test Config Schema

See: https://calycode.com/schemas/testing/config.json

Test Config Example (JSON)

[
   {
      "path": "/auth/login",
      "method": "POST",
      "headers": {},
      "queryParams": null,
      "requestBody": {
         "email": "{{ENVIRONMENT.TEST_EMAIL}}",
         "password": "{{ENVIRONMENT.TEST_PASSWORD}}"
      },
      "store": [{ "key": "AUTH_TOKEN", "path": "$.authToken" }],
      "customAsserts": {}
   },
   {
      "path": "/users/me",
      "method": "GET",
      "headers": { "Authorization": "Bearer {{ENVIRONMENT.AUTH_TOKEN}}" },
      "queryParams": null,
      "requestBody": null,
      "customAsserts": {}
   }
]

Test Config Example (JavaScript with Custom Asserts)

// test-config.js
module.exports = [
   {
      path: '/health',
      method: 'GET',
      headers: {},
      queryParams: null,
      requestBody: null,
      customAsserts: {
         hasStatus: {
            fn: (ctx) => {
               if (!ctx.result?.status) throw new Error('Missing status');
            },
            level: 'error',
         },
      },
   },
];

Local Servers

Serve OpenAPI Spec

# Default port 5000
xano serve spec

# Custom port with CORS
xano serve spec --listen 8080 --cors

Opens Scalar API Reference for testing APIs locally.

Serve Registry

xano serve registry --root ./my-registry --listen 5500

Options

Registry (Component Sharing)

Add Component from Registry

xano registry add component-name

# Multiple components
xano registry add auth-flow user-management

# Custom registry URL
xano registry add component-name --registry https://my-registry.com/definitions

Scaffold New Registry

xano registry scaffold --output ./my-registry

Creates a registry folder with sample component following the schema.

Registry Schemas

• Registry: https://calycode.com/schemas/registry/registry.json
• Registry Item: https://calycode.com/schemas/registry/registry-item.json

AI Integration (OpenCode)

Uses the latest available OpenCode version via npx opencode. Use this when requiring custom subagents to work on subtasks. More on OpenCode here: https://opencode.ai/docs

Initialize OpenCode Host

xano oc init

Sets up native host integration for the @calycode extension.

Serve OpenCode Server

# Default port 4096
xano oc serve

# Custom port, detached mode
xano oc serve --port 8000 --detach

Execute OpenCode CLI commands:

# Run any task with OpenCode
xano oc run "/review"

Common Context Options

Most commands accept these context options:

Typical Workflows

Initial Setup

# 1. Initialize
xano init --name prod --url https://x123.xano.io --token $TOKEN --directory ./project

# 2. Generate OpenAPI specs
xano generate spec --all

# 3. Generate TypeScript client
xano generate codegen --generator typescript-axios --all

CI/CD Pipeline

# Generate specs and client
xano generate spec --all
xano generate codegen --generator typescript-fetch --all
# Optionally here do logic that would move your genreted library as an (internal) npm-package for reuse in FE projects

# Run tests
xano test run --test-config-path ./test-config.json --all

# Create backup
xano backup export

Local Development

# Serve OpenAPI docs locally
xano serve spec --listen 5000 --cors

# In another terminal, serve registry
xano serve registry --root ./registry --listen 5500

Troubleshooting

Resources

• GitHub: https://github.com/calycode/xano-tools
• Discord: https://links.calycode.com/discord
• Test Config Schema: https://calycode.com/schemas/testing/config.json
• Registry Schema: https://calycode.com/schemas/registry/registry.json

Converted and distributed by TomeVault — claim your Tome and manage your conversions.