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. 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 all local .xs files back to your Xano workspace, syncing your local changes. The CLI recursively collects all .xs files from the directory, sorts them alphabetically, combines them into a single payload, and sends them to Xano. After completion, the CLI displays the total execution time.
FlagDescription
-bBranch name (overrides profile; defaults to live branch)
-wWorkspace ID (overrides profile)
--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 automatic preview and confirmation prompt — useful for CI/CD pipelines
--partialPush without requiring a workspace block — useful for pushing a subset of files
--deleteDelete objects in Xano that are not present in the push
--no-sync-guidsSkip writing server-assigned GUIDs back to local files
--truncateTruncate all table records before importing
Push replaces the workspace’s XanoScript content with what you send. 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 --partial if you only need to update specific resources.
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.

​
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.

​
Skipping preview

Use --force to bypass the preview and confirmation prompt entirely — useful in CI/CD pipelines or scripted workflows:
In non-interactive environments (e.g. piped output), the CLI detects that it cannot prompt for confirmation, warns you, and proceeds automatically — as if --force were set.

​
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

​
Partial push (no workspace block required)

Use --partial to push a subset of your local files — for example, just an API group, a set of functions, or a single endpoint — without needing a workspace.xs file in the push. The workspace is identified via your profile or -w flag instead. For example, if your workspace looks like this: 
my-workspace/
├── workspace/
│   └── my_workspace.xs
├── table/
├── function/
└── api/
    └── my_api/
        ├── api_group.xs
        ├── get_users_get.xs
        └── create_user_post.xs
You can push just the API group: Key behaviors --partial enables:
  • No workspace block required — a full push needs a workspace.xs file to identify the workspace; --partial skips that requirement
  • Implies --no-delete — objects on the remote that aren’t in your partial push are left alone; only the files you’re pushing are created or updated
  • Scoped updates — push just functions, a single API group, middleware, or any other subset without touching the rest of the workspace
Without --partial, pushing a subfolder would fail because there’s no workspace block to identify the workspace.

​
Delete removed objects

Use --delete to remove any objects in Xano that are not present in your local files. This ensures your workspace matches your local directory exactly.
The --delete flag 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-sync-guids to skip this step — useful in CI/CD pipelines or when you don’t want local files modified.

​
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 --partial when you only need to push a few specific resources instead of the entire workspace.
  • 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: