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.
Terminal
xano workspace pull ./my-workspace
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

Terminal
xano workspace pull ./my-workspace --env

​
Include database records

Terminal
xano workspace pull ./my-workspace --records

​
Both

Terminal
xano workspace pull ./my-workspace --env --records

​
Pull a specific branch

Terminal
xano workspace pull ./my-workspace -b v2-feature
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.
Terminal
xano workspace push ./my-workspace
The CLI recursively collects all .xs files from the directory, sorts them alphabetically, combines them into a single payload, and sends them to Xano.
FlagDescription
-bBranch name (overrides profile; defaults to live branch)
-wWorkspace ID (overrides profile)
--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-recordsSkip importing table records (push schema only)
--no-envSkip overwriting environment variables
--truncateTruncate all table records before importing
Push replaces the workspace’s XanoScript content with what you send. Make sure your local files are up to date before pushing. It is recommended to work on a non-live branch and test before promoting to live.

​
Push Options

​
Push schema only (skip records)

Terminal
xano workspace push ./my-workspace --no-records

​
Push without overwriting environment variables

Terminal
xano workspace push ./my-workspace --no-env

​
Partial push (no workspace block required)

Use --partial to push a subset of files without needing a complete workspace block. This is useful when you only want to update specific resources.
Terminal
xano workspace push ./my-workspace --partial

​
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.
Terminal
xano workspace push ./my-workspace --delete
The --delete flag will permanently remove objects from your Xano workspace that don’t exist in the local push. Double-check your local files before using this flag.

​
Truncate table records before importing

Terminal
xano workspace push ./my-workspace --truncate

​
Combine flags

Terminal
xano workspace push ./my-workspace --no-records --no-env

​
Typical Workflow

A common development cycle looks like this:
1

Pull the latest

Terminal
xano workspace pull ./my-workspace
2

Make changes locally

Edit .xs files in your editor of choice. Use the XanoScript VS Code Extension for syntax highlighting and autocomplete.
3

Push changes back

Terminal
xano workspace push ./my-workspace
4

Test in Xano

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

​
https://mintcdn.com/xano-997cb9ee/How4y2-NUVnTIPUm/images/icons/GitHub_light.svg?fit=max&auto=format&n=How4y2-NUVnTIPUm&q=85&s=7304b7cb9606506e332ca0504388559ehttps://mintcdn.com/xano-997cb9ee/How4y2-NUVnTIPUm/images/icons/GitHub_dark.svg?fit=max&auto=format&n=How4y2-NUVnTIPUm&q=85&s=adb0b7079fcba72618143a25d1fafdff https://mintcdn.com/xano-997cb9ee/l34pjCw6QluB5NGI/images/icons/gitlab.svg?fit=max&auto=format&n=l34pjCw6QluB5NGI&q=85&s=9c4f55426b9ab4cbeabe567578ad364a 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:
Terminal
cd my-workspace
git init
git add .
git commit -m "Initial pull from Xano"
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.
  • 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:
Terminal
xano workspace push ./my-workspace -v
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:
Terminal
export XANO_VERBOSE=true
xano workspace pull ./my-workspace