> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Static Hosting

> Deploy and manage static frontend builds from the CLI

export const BrowserFrame = props => {
  const {url = "xano.run", maxWidth = 820, className = "", lightSrc, darkSrc, alt = "", children} = props || ({});
  const style = typeof maxWidth === "number" ? {
    maxWidth: `${maxWidth}px`,
    margin: "16px 0"
  } : {
    maxWidth,
    margin: "16px 0"
  };
  const hasSwapImages = Boolean(lightSrc && darkSrc);
  return <div className={`browser-frame ${className}`.trim()} style={style}>
      <div className="browser-frame__top">
        <div className="browser-frame__controls" aria-hidden="true">
          <span className="browser-frame__dot browser-frame__dot--red" />
          <span className="browser-frame__dot browser-frame__dot--yellow" />
          <span className="browser-frame__dot browser-frame__dot--green" />
        </div>
        <div className="browser-frame__address">{url}</div>
      </div>

      <div className="browser-frame__body">
        {hasSwapImages ? <>
            <img className="browser-frame__img--light" src={lightSrc} alt={alt} />
            <img className="browser-frame__img--dark" src={darkSrc} alt={alt} />
          </> : children}
      </div>
    </div>;
};

Static hosting lets you serve frontend assets (HTML, CSS, JavaScript, images) directly from Xano alongside your backend APIs. This is useful for single-page applications, marketing sites, documentation, or any static content that pairs with your Xano backend.

The CLI manages static hosting as a full lifecycle: create a host, push versioned builds (from a directory or a zip), deploy them to the **dev** and **prod** environments, and pull builds back to disk. Each host has two environments, and builds are promoted into them with `deploy`.

<Note>
  Static host commands require a workspace ID, either from your profile or via the `-w` flag. Static hosts are referenced by **name**, and builds are referenced by **ID** (`--build_id`).
</Note>

## Managing Static Hosts

### List Static Hosts

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host list
  ```
</BrowserFrame>

Each static host shows its name, ID, and domain (if configured). Use `-o json` for the full JSON response.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host list -o json
  ```
</BrowserFrame>

| Flag         | Description                                  |
| ------------ | -------------------------------------------- |
| `-w`         | Workspace ID                                 |
| `-o`         | Output format: `summary` (default) or `json` |
| `--page`     | Page number for pagination (default: `1`)    |
| `--per_page` | Results per page (default: `50`)             |

### Create a Static Host

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host create marketing
  xano static_host create marketing --description "Marketing site"
  ```
</BrowserFrame>

| Flag            | Description                                  |
| --------------- | -------------------------------------------- |
| `--description` | Description for the static host              |
| `-w`            | Workspace ID                                 |
| `-o`            | Output format: `summary` (default) or `json` |

### Get a Static Host

Inspect a single host — its description, git configuration, and the URLs deployed to its dev and prod environments.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host get marketing
  ```
</BrowserFrame>

| Flag | Description                                  |
| ---- | -------------------------------------------- |
| `-w` | Workspace ID                                 |
| `-o` | Output format: `summary` (default) or `json` |

### Edit a Static Host

Update a host's name, description, or git configuration. Provide at least one of `--name`, `--description`, or a `--git-*` flag.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host edit marketing --description "Updated marketing site"
  xano static_host edit marketing --name marketing-v2
  ```
</BrowserFrame>

<Warning>
  Renaming a host changes its deployed hostname.
</Warning>

| Flag                     | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `--name`                 | New name for the static host (renaming changes the deployed hostname)                                |
| `--description`          | New description                                                                                      |
| `--git-repo`             | Git repository URL (e.g. `git@github.com:org/repo.git`)                                              |
| `--git-public-key`       | Git SSH public key                                                                                   |
| `--git-private-key-file` | Path to a file containing the git SSH private key (read from disk; never passed on the command line) |
| `-w`                     | Workspace ID                                                                                         |
| `-o`                     | Output format: `summary` (default) or `json`                                                         |

***

## Builds

Builds are versioned snapshots of your static assets. Each static host can have multiple builds, letting you track deployment history and manage versions. You upload them with `build push` and promote them to an environment with `deploy`.

### List Builds

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host build list marketing
  ```
</BrowserFrame>

Each build shows its name, ID, and status. Use `-o json` for full details.

| Flag         | Description                                  |
| ------------ | -------------------------------------------- |
| `-w`         | Workspace ID                                 |
| `-o`         | Output format: `summary` (default) or `json` |
| `--page`     | Page number for pagination (default: `1`)    |
| `--per_page` | Results per page (default: `50`)             |

### Get Build Details

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host build get marketing --build_id 52
  ```
</BrowserFrame>

| Flag         | Description                                  |
| ------------ | -------------------------------------------- |
| `--build_id` | Build ID (required)                          |
| `-w`         | Workspace ID                                 |
| `-o`         | Output format: `summary` (default) or `json` |

### Push a Build

`build push` is the primary way to upload a build. Point it at a **directory** (`-d`, which the CLI zips for you) or an existing **zip file** (`-f`). If you omit both, it pushes the current directory.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # Push a directory (zipped for you) with an explicit name
  xano static_host build push marketing -d ./dist -n "v1.0.0"
  ```
</BrowserFrame>

The build **name is optional** — when omitted it's auto-generated from the current timestamp (e.g. `20260531-143022`):

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # Push the current directory with an auto-generated name
  xano static_host build push marketing
  ```
</BrowserFrame>

You can also push an existing zip file directly:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host build push marketing -f ./build.zip -n "v1.0.0"
  ```
</BrowserFrame>

On success, `build push` reports the file count and upload size and prints the resulting static host URLs:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  $ xano static_host build push marketing -d ./dist -n "v1.0.0"
  Pushed 15 files as build "v1.0.0" (1.2 MB)
  ID: 123
  Dev URL: https://example-dev.static.xano.io
  ```
</BrowserFrame>

<Note>
  For builds that include a `package.json`, the build runs asynchronously on Xano after upload. By default the CLI **waits for the build to finish** and reports its final status. Pass `--no-wait` to return immediately after upload instead.
</Note>

| Flag              | Description                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `-d, --directory` | Directory to push, zipped automatically (defaults to the current directory; mutually exclusive with `-f`) |
| `-f, --file`      | Path to a zip file to upload (mutually exclusive with `-d`)                                               |
| `-n, --name`      | Build name (auto-generated from the current timestamp if omitted)                                         |
| `--description`   | Build description                                                                                         |
| `--no-wait`       | Return immediately after upload instead of waiting for the build to finish                                |
| `-w`              | Workspace ID                                                                                              |
| `-o`              | Output format: `summary` (default) or `json`                                                              |

<Warning>
  `xano static_host build create` is deprecated. Its zip-upload capability has been folded into `build push` — use `xano static_host build push -f <file>` instead.
</Warning>

### Pull a Build

Download a build to disk. Select the build by ID (`--build_id`), the most recent build (`--latest`), or the build currently deployed to an environment (`--env dev|prod`). Exactly one of these is required.

By default, `build pull` downloads the **original uploaded source** (including `package.json`). Pass `--source built` to fetch the compiled/served output instead.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # By build ID, into the current directory
  xano static_host build pull marketing --build_id 52

  # The latest build, into a specific directory
  xano static_host build pull marketing --latest -d ./output

  # The build currently deployed to prod
  xano static_host build pull marketing --env prod -d ./prod-release

  # The compiled/served output rather than the uploaded source
  xano static_host build pull marketing --build_id 52 --source built
  ```
</BrowserFrame>

| Flag              | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--build_id`      | Build ID to pull (mutually exclusive with `--latest` and `--env`)                                                                 |
| `--latest`        | Pull the most recent build (mutually exclusive with `--build_id` and `--env`)                                                     |
| `--env`           | Pull the build currently deployed to this environment: `dev` or `prod` (mutually exclusive with `--build_id` and `--latest`)      |
| `-d, --directory` | Output directory for pulled files (defaults to the current directory)                                                             |
| `--source`        | Which files to pull: `original` (default — the uploaded source, including `package.json`) or `built` (the compiled/served output) |
| `-w`              | Workspace ID                                                                                                                      |

### Delete a Build

Delete a build permanently. This prompts for confirmation unless you pass `--force`.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host build delete marketing --build_id 52
  xano static_host build delete marketing --build_id 52 --force
  ```
</BrowserFrame>

| Flag          | Description                                  |
| ------------- | -------------------------------------------- |
| `--build_id`  | Build ID to delete (required)                |
| `-f, --force` | Skip the confirmation prompt                 |
| `-w`          | Workspace ID                                 |
| `-o`          | Output format: `summary` (default) or `json` |

***

## Deploy

Promote a build to an environment. A host has two environments — `dev` and `prod` — and `deploy` points the chosen environment at a specific build.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  xano static_host deploy marketing --build_id 52 --env dev
  xano static_host deploy marketing --build_id 52 --env prod
  ```
</BrowserFrame>

On success, `deploy` prints the resulting URL for that environment.

| Flag         | Description                                    |
| ------------ | ---------------------------------------------- |
| `--build_id` | Build ID to deploy (required)                  |
| `--env`      | Target environment: `dev` or `prod` (required) |
| `-w`         | Workspace ID                                   |
| `-o`         | Output format: `summary` (default) or `json`   |

***

## Migrate to v2 Hosting

`migrate` moves static hosts from the older v1 hosting to **instance-managed (v2)** hosting.

<Note>
  **Instance-managed (v2) hosting** serves your static sites from a fully containerized environment inside your Xano instance. It removes some of the external dependencies that made the original (v1) hosting less flexible for certain setups, giving you more control over how your frontend is served.
</Note>

You can migrate a single host, a single environment of a host, or every v1 host in the workspace with `--all`. Use `--dry-run` to preview what would change without applying anything.

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # Migrate one host (both environments)
  xano static_host migrate marketing

  # Migrate one environment of a host
  xano static_host migrate marketing --env dev

  # Migrate every v1 host in the workspace
  xano static_host migrate --all

  # Preview what --all would do, without changing anything
  xano static_host migrate --all --dry-run
  ```
</BrowserFrame>

Provide either a static host name or `--all`, not both.

| Flag        | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `--all`     | Migrate every host still on v1 in the workspace                          |
| `--env`     | Which environment to migrate: `dev` or `prod` (migrates both if omitted) |
| `--dry-run` | List the hosts that would be migrated without changing anything          |
| `-w`        | Workspace ID                                                             |
| `-o`        | Output format: `summary` (default) or `json`                             |

***

## Typical Workflow

A common pattern for deploying a frontend alongside your Xano backend:

<BrowserFrame url="Terminal">
  ```bash theme={null}
  # Build your frontend (React, Vue, Svelte, etc.)
  npm run build

  # Push the build output directory — the CLI zips it for you
  xano static_host build push marketing -d ./dist -n "v1.2.0"

  # Promote that build to an environment
  xano static_host deploy marketing --build_id 123 --env prod
  ```
</BrowserFrame>

<Tip>
  Name your builds with version numbers so you can easily identify them later when listing builds. If you skip `-n`, the CLI assigns a sortable timestamp name automatically.
</Tip>


## Related topics

- [Static Hosting](/xano-features/static-hosting.md)
- [Deployment](/deployment.md)
- [Update static hosting environment](/api-reference/static-host/update-static-hosting-environment.md)