Skip to main content
The Xano CLI lets you pull your entire workspace down as XanoScript files and push local changes back. This enables local development, version control with Git, AI-assisted development, and team collaboration.

​
Pull

Pull downloads your workspace as individual .xs (XanoScript) files, organized by type. Behind the scenes, the CLI retrieves a single multidoc — a combined XanoScript document containing every definition in your workspace — and splits it into separate files. This creates a directory structure like: 
my-workspace/
├── workspace/
│   ├── my_workspace.xs
│   └── trigger/
│       └── on_workspace_event.xs
├── table/
│   ├── user.xs
│   ├── product.xs
│   └── trigger/
│       └── on_user_create.xs
├── function/
│   ├── calculate_shipping.xs
│   └── utils/
│       └── validate_email.xs
├── api/
│   ├── user/
│   │   ├── api_group.xs
│   │   ├── get_user_get.xs
│   │   └── create_user_post.xs
│   └── product/
│       ├── api_group.xs
│       └── list_products_get.xs
├── task/
│   └── cleanup_expired_sessions.xs
├── ai/
│   ├── agent/
│   │   ├── support_bot.xs
│   │   └── trigger/
│   │       └── on_agent_event.xs
│   ├── tool/
│   │   └── search_knowledge_base.xs
│   └── mcp_server/
│       ├── my_mcp_server.xs
│       └── trigger/
│           └── on_mcp_event.xs
├── realtime/
│   ├── channel/
│   │   └── notifications.xs
│   └── trigger/
│       └── on_message.xs
├── middleware/
│   └── auth_check.xs
└── addon/
    └── fetch_related.xs
Each resource becomes its own .xs file. Key details:
  • API endpoints are grouped under api/{group_name}/ directories, with each group containing an api_group.xs and endpoint files named {name}_{verb}.xs
  • Hierarchical functions (with / in the name) are split into subdirectories
  • AI resources (agents, tools, MCP servers) are grouped under ai/, with triggers in ai/{type}/trigger/
  • Realtime resources are organized under realtime/channel/ and realtime/trigger/
  • Triggers are placed in trigger/ subdirectories within their parent type (table/trigger/, ai/agent/trigger/, etc.)
  • All filenames are converted to snake_case

​
Pull Options

FlagDescription
-bBranch name (overrides profile; defaults to live branch)
-wWorkspace ID (overrides profile)
--envInclude environment variables
--recordsInclude database records
--draftInclude draft versions of resources

​
Include environment variables

​
Include database records

Pull your table records alongside the schema. This is also a convenient way to create a local backup of your data before pushing schema changes.

​
Both

​
Pull a specific branch

If -b is not provided, the pull targets the branch stored in your profile. If no branch is set in your profile, it defaults to the live branch.

​
Push

Push uploads local .xs files back to your Xano workspace, syncing your local changes. By default, only changed files are pushed (partial mode). Use --sync to push all files. The CLI recursively collects all .xs files from the directory, compares them against your workspace, and sends only the changes to Xano. Before applying anything, the CLI shows a preview of what will be created, updated, or deleted, and prompts for confirmation. After completion, the CLI displays the total execution time.
FlagDescription
-bBranch name (overrides profile; defaults to live branch)
-wWorkspace ID (overrides profile)
-f, --filterGlob pattern to filter files (e.g. -f "function/*" or -f "**/book*"). Supports multiple -f flags.
--syncFull push — send all files, not just changed ones. Required for --delete.
--deleteDelete workspace objects not included in the push (requires --sync)
--recordsInclude table records in the push — requires local files pulled with --records
--envInclude environment variables in the push — requires local files pulled with --env
--dry-runShow the push preview, then exit without applying changes
--forceSkip the preview and confirmation prompt — also overrides critical error blocking. Required in non-interactive (CI/CD) environments.
--no-guidsSkip writing server-assigned GUIDs back to local files
--no-transactionSkip wrapping the import in a database transaction — useful for debugging failed imports
--truncateTruncate all table records before importing
Every push automatically shows a preview of what will change and prompts for confirmation — but that’s your last line of defense, not your first.Before pushing: make sure your local files are up to date (pull first), review your changes with git diff, and consider pulling with --records to snapshot your data before schema changes. Work on a non-live branch and test before promoting to live. Use -f to filter specific files if you only need to update a subset.
See Push Options for detailed usage of each flag.

​
Push Preview

Every xano workspace push automatically runs a preview before making any changes. The CLI performs a dry-run against your Xano instance and shows you exactly what will happen — then prompts for confirmation before proceeding. If there are no changes to apply, the CLI exits with No changes to push. If changes are detected, the preview is shown before the confirmation prompt. When records are included (--records), the preview also shows record counts per table.

​
Summary & Changes

The preview opens with a per-type count of what will be created, updated, or deleted — color-coded green, yellow, and red — followed by the non-destructive operations: new objects being created (CREATE), existing objects being updated (UPDATE), and fields being added or modified (ADD_FIELD, UPDATE_FIELD). CLI push preview — changes

​
Destructive Operations

Operations that can cause data loss are listed separately and highlighted: DELETE, CASCADE_DELETE, TRUNCATE, DROP_FIELD, and ALTER_FIELD. When destructive operations are present, the confirmation prompt explicitly warns you before asking to proceed. CLI push preview — destructive operations CLI push preview — destructive operations 2

​
Remote Only

Objects that exist in your Xano workspace but are not in your local files. These are shown when --delete is not set — they will not be deleted, but the preview makes them visible so you’re aware of the discrepancy. CLI push preview — remote only

​
Verbose mode

Add -v to see a reason line under each operation explaining why the server classified it that way:

​
Preview only (dry run)

Use --dry-run to see the full preview — changes, destructive operations, remote-only items, and records — then exit without pushing. Nothing is applied. This is useful when you want to inspect what a push would do before committing to it — especially helpful for AI agents that need to review the impact of changes before deciding to proceed.

​
Critical error blocking

Pushes that contain critical errors — such as XanoScript syntax errors or unresolved placeholders — are automatically blocked. The preview highlights these errors so you can fix them before retrying. Use --force to override and push anyway.

​
Skipping preview

Use --force to bypass the preview and confirmation prompt entirely — useful in CI/CD pipelines or scripted workflows. --force also overrides critical error blocking.
In non-interactive environments (e.g. piped output, CI/CD), the CLI requires --force to skip the confirmation prompt.

​
Push Options

​
Push with records

Records are off by default on push, matching pull behavior. To include records, you must have first pulled with --records (so the data exists locally), then explicitly pass --records on push:

​
Push with environment variables

Environment variables are also off by default on push. Pull with --env first, then push with --env:

​
Push with records and environment variables

​
File filtering

Use -f (or --filter) to push only files matching a glob pattern. Patterns are matched against relative paths from the push directory. You can pass multiple -f flags to combine patterns.

​
Full sync

By default, only changed files are pushed. Use --sync to push all files — this performs a full sync against your workspace.

​
Delete removed objects

Use --sync --delete to remove any objects in Xano that are not present in your local files. This ensures your workspace matches your local directory exactly. --delete requires --sync.
--sync --delete will permanently remove objects from your Xano workspace that don’t exist in the local push. Double-check your git diff to be confident before using this flag.

​
Skip GUID sync

By default, after a push the CLI writes server-assigned GUIDs back into your local .xs files. Use --no-guids to skip this step — useful in CI/CD pipelines or when you don’t want local files modified.

​
Skip transaction

By default, pushes are wrapped in a database transaction so that failures roll back cleanly. Use --no-transaction to disable this — useful for debugging failed imports where you want to inspect the partial state.

​
Truncate table records before importing (staging/test workspaces only)

Use --truncate to wipe all existing rows from every table before importing records from your local files. This is useful when you want a clean slate — for example, resetting a staging or test workspace to a known dataset before running automated tests, or re-seeding a fresh environment with fixture data.
--truncate deletes all existing table records before importing. It is intended for staging and test workspaces only — never use it against a production workspace. The push preview always lists truncation under Destructive Operations so you can verify it’s expected before confirming.

​
Pull from Git

You can pull XanoScript files directly from a Git repository (GitHub, GitLab, or any git URL) into a local directory — without needing to clone the repo yourself. This fetches all .xs files from the repository and organizes them into the same directory structure as a workspace pull.

​
Git Pull Options

FlagDescription
-rGit repository URL (required) — supports HTTPS, SSH, GitHub, and GitLab URLs
-bBranch, tag, or ref to fetch (defaults to the repository’s default branch)
-tPersonal access token for private repos (falls back to GITHUB_TOKEN env var)
--pathSubdirectory within the repo to import from

​
URL Formats

You can pass a variety of URL formats — the CLI extracts the owner, repo, branch, and path automatically:
For GitHub repos, the CLI uses the tarball API for fast downloads without requiring git to be installed. For GitLab and other hosts, it falls back to a shallow git clone.

​
Workflow: Import from Git, Push to Xano

A common use case is pulling XanoScript from a shared Git repository and pushing it to a workspace. For example, you can pull the Hello World sample from the XanoScript examples repo and push it to your workspace:

​
Typical Workflow

A common development cycle looks like this:
1

Pull the latest

2

Make changes locally

Edit .xs files in VS Code with the XanoScript Language Server extension for syntax highlighting and inline validation.
Use AI-assisted development with Claude Code and the Xano Developer MCP to generate and modify XanoScript with AI — the MCP provides documentation and real-time validation directly to your AI assistant.
3

Review changes with Git

Before pushing, review exactly what changed using Git:Pay close attention to any table schema changes — renamed columns, removed fields, or changed field types — as these can affect existing data.
4

Preview the push

Run a dry run to see exactly what the push will do — without applying anything:Review the output for any unexpected changes, especially destructive operations or schema modifications.
5

Push changes back

Once you’re satisfied with the preview, run the actual push. The CLI shows the same preview again and prompts for confirmation before applying:
6

Test in Xano

Verify your changes in the Xano dashboard or via API calls.

​
https://mintcdn.com/xano-997cb9ee/aZQYcxhIvSDTNEim/images/icons/GitHub_light.svg?fit=max&auto=format&n=aZQYcxhIvSDTNEim&q=85&s=43b6a62193d3b7677b1507f3851c13c6https://mintcdn.com/xano-997cb9ee/aZQYcxhIvSDTNEim/images/icons/GitHub_dark.svg?fit=max&auto=format&n=aZQYcxhIvSDTNEim&q=85&s=744195baf98992d8c2e009ffafe0b937 https://mintcdn.com/xano-997cb9ee/aZQYcxhIvSDTNEim/images/icons/gitlab.svg?fit=max&auto=format&n=aZQYcxhIvSDTNEim&q=85&s=8ee5edf2535d88a8b345481d673c1b9e Git works like it always has

Your workspace is plain files on disk — git init, commit, branch, and open PRs exactly like any other project. Xano’s push/pull fits into your Git workflow, not the other way around.

​
Working with Git

Since pull outputs standard files to your filesystem, you can version control your XanoScript with Git: This gives you full commit history, diffs, branching, and collaboration through Git — on top of Xano’s own branching system.

​
Tips

  • Pull before you push to avoid overwriting changes made by teammates in the Xano dashboard.
  • Use branches for development work. Create a branch with xano branch create -l dev, then use -b dev on push and pull commands to target it without affecting the live branch.
  • Snapshot your data by pulling with --records before pushing schema changes. This gives you a local copy of your database records you can restore from if needed. To push those records back, pass --records on push as well — records are off by default in both directions.
  • Use -f to filter when you only need to push specific files (e.g. -f "function/*"). Use --sync when you need a full push, and --sync --delete to remove remote objects not in your local files.
  • Combine with AI tools like Claude Code or Cursor to generate and edit XanoScript locally, then push the results. See the Start from Scratch and Work from Existing guides for full walkthroughs.

​
Troubleshooting

If a push or pull isn’t working as expected, use the -v (verbose) flag to see the full request and response details: Verbose mode shows:
  • The HTTP method and full URL being called
  • Request headers (with the authorization token partially masked)
  • The request body (truncated to 500 characters for readability)
  • The response status code and elapsed time
This works on all CLI commands, not just push and pull. You can also enable it globally by setting the XANO_VERBOSE environment variable: