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

# CLI

> Install the SandyWP CLI, authenticate once, and manage WordPress sandboxes from your terminal.

The `sandywp` CLI is the quickest way to work with SandyWP from a terminal. It uses the same account and API as the dashboard.

## Install and authenticate

<Tabs>
  <Tab title="Install globally">
    ```sh theme={null}
    npm install -g @sandywp/cli
    sandywp auth login
    ```
  </Tab>

  <Tab title="Run with npx">
    ```sh theme={null}
    npx @sandywp/cli auth login
    ```
  </Tab>
</Tabs>

The login command opens a browser for approval and stores the resulting personal token in `~/.sandywp/config.json`. For CI or another headless environment, pass an existing token directly.

```sh theme={null}
sandywp auth login --token "$SANDYWP_TOKEN"
```

<Warning>
  A personal token has full account access. Store it in a secret manager or CI secret, never in source control.
</Warning>

## Everyday commands

| Command                              | What it does                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `sandywp add [name]`                 | Create a sandbox and wait for readiness. Use `--no-wait` to return after queueing it. |
| `sandywp list`                       | List sandboxes.                                                                       |
| `sandywp status`                     | Show account plan and current usage.                                                  |
| `sandywp login <name> --open`        | Open a magic `wp-admin` login link.                                                   |
| `sandywp deploy <name> <plugin.zip>` | Install and activate a plugin ZIP.                                                    |
| `sandywp delete <name>`              | Delete a sandbox by slug or ID.                                                       |

```sh theme={null}
sandywp add my-plugin-test
sandywp deploy my-plugin-test ./dist/my-plugin.zip
sandywp login my-plugin-test --open
```

## Push a local WordPress site

Run `sandywp push` from anywhere inside a local WordPress installation. The first push creates a sandbox, restores the database and `wp-content`, then writes a local `.sandywp` link file.

Later pushes update that same sandbox in place and overwrite its database and files. Add `.sandywp` to `.gitignore`; it links one local folder to one SandyWP sandbox.

```sh theme={null}
cd ~/Sites/my-local-site
sandywp push

# Skip the overwrite confirmation in automation.
sandywp push --force
```

You need a running local database and either `wp` (WP-CLI) or `php` on `PATH`. See [Push a local site](/guides/push-local-site) for requirements and troubleshooting.

## SSH and mounts

The CLI can open a sandbox shell without manual key setup. It can also mount the sandbox files as a local directory.

```sh theme={null}
# Open a shell, or run one command and exit.
sandywp ssh my-site
sandywp ssh my-site --cmd "wp plugin list"

# Mount files at ~/SandyWP/my-site by default.
sandywp mount my-site
sandywp mounts
sandywp unmount my-site
```

SSH and mounting require an account-owned ready sandbox on a paid plan. Mounting also needs a FUSE provider; see [SSH access](/guides/ssh-access) and [Mount a sandbox](/guides/mount-a-sandbox).

## Blueprints and templates

Use the CLI to manage repeatable Blueprint recipes and reusable Templates. `--wait` is useful in CI because it waits for a Blueprint bake to finish.

```sh theme={null}
sandywp blueprint create "Plugin recipe" blueprint.json
sandywp blueprint validate blueprint.json
sandywp blueprint bake plugin-recipe --wait

sandywp template list
sandywp template launch plugin-recipe enable
```

`sandywp blueprint import` fetches a recipe from a URL, and `sandywp blueprint runs` lists individual create, apply, and bake attempts. See [Blueprints](/guides/blueprints) and [Templates](/guides/templates).

## Workspaces and useful flags

Use `sandywp workspace list` to see workspaces and `sandywp workspace use <id-or-slug>` to set the saved default. A command can target a different workspace once with `--workspace <id-or-slug>` or its legacy `--org` alias.

| Flag                 | Use                                                       |
| -------------------- | --------------------------------------------------------- |
| `--base-url <url>`   | Use a non-default API host during login.                  |
| `--no-browser`       | Print the device authorization URL instead of opening it. |
| `--no-wait`          | Return from `add` before provisioning completes.          |
| `--force`            | Skip the `push` overwrite prompt.                         |
| `--open`             | Open a login or push URL in the browser.                  |
| `--cmd <command>`    | Run a single SSH command.                                 |
| `--path <directory>` | Use a specific mount directory.                           |

The CLI is a practical wrapper around the REST API. See [API Reference](/api-reference) when you need direct HTTP calls; the published OpenAPI schema covers the complete supported customer API contract.