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

# ShardCloud CLI

> This package provides a direct way to interact with the official ShardCloud API.

## Installation

Repo: [https://github.com/shard-cloud/cli](https://github.com/shard-cloud/cli)

To install the CLI, just run the following command in your terminal:

macOS, Linux, and WSL:

```bash theme={null}
curl -fsSL https://cli.shardcloud.app | bash
```

Windows | need [npm](https://www.npmjs.com/) installed:

```bash theme={null}
npm install -g shard-cloud-cli
```

## v2: Resource-Grouped Commands

<Warning>
  CLI v2 replaces v1's flat command surface entirely. This is a breaking
  change — there are no aliases for the old verbs, so any scripts calling
  `shardcloud <verb> <id>` directly need to be updated. See [Migrating from
  v1](#migrating-from-v1) below.
</Warning>

Every command is now `shardcloud <resource> <verb>`, grouped by the kind of thing it acts on:

```bash theme={null}
shardcloud app restart <id>
shardcloud db create --type postgres --name mydb --ram 512
shardcloud vm ssh <id>
```

Run `shardcloud <resource> --help` for the full list of subcommands in a group, or see the [full command reference](/cli/commands).

| Group                                        | Description                                                                        |
| -------------------------------------------- | ---------------------------------------------------------------------------------- |
| `auth`                                       | Log in/out, show the current account                                               |
| `config`                                     | Manage auth profiles and CLI settings                                              |
| `link` / `unlink`                            | Link the current directory to an existing app, database, or VM                     |
| `app`                                        | Create, deploy, and manage apps                                                    |
| `db`                                         | Create and manage databases                                                        |
| `vm`                                         | Manage virtual machines, including SSH access                                      |
| `backup`                                     | Create, list, restore, delete, and download backups — for apps, databases, and VMs |
| `lb`                                         | Manage load balancers (**Pro and Enterprise plans only**)                          |
| `image`                                      | Build, deploy, and manage custom Docker images                                     |
| `version` / `update` / `completion` / `docs` | CLI version, update check, shell completions, and opening these docs               |

## Authentication

See [Authentication](/cli/auth) for logging in, profiles, and non-interactive/CI auth.

## Global Output Flags

Every command accepts two persistent flags that control how output is printed, useful for scripting:

| Flag      | Effect                                                            |
| --------- | ----------------------------------------------------------------- |
| `--json`  | Print machine-readable JSON instead of a table                    |
| `--quiet` | Print only IDs (one per line) — nothing else, no success messages |

```bash theme={null}
shardcloud app list --json
shardcloud app list --quiet | xargs -n1 shardcloud app restart
```

## Update

To update the CLI, just run the following command in your terminal:

macOS, Linux, and WSL:

```bash theme={null}
curl -fsSL https://cli.shardcloud.app | bash
```

Windows | need [npm](https://www.npmjs.com/) installed:

```bash theme={null}
shardcloud update
```

The CLI also nudges you in place when a newer version is available (after any command finishes, in table output mode), and `shardcloud update` checks and prints the right upgrade command for your platform on demand.

### Install a specific version (NPM only)

```bash theme={null}
shardcloud install 2.0.0
```

## Migrating from v1

v1's flat verbs are gone — every one of them now lives under a resource group. There are no aliases; the table below maps every old command to its v2 equivalent.

| v1                            | v2                                                                                            |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| `shardcloud login`            | `shardcloud auth login`                                                                       |
| `shardcloud logout`           | `shardcloud auth logout`                                                                      |
| `shardcloud me`               | `shardcloud auth whoami`                                                                      |
| `shardcloud create`           | `shardcloud app create`                                                                       |
| `shardcloud commit <app_id>`  | `shardcloud app commit <app_id>`                                                              |
| `shardcloud status <app_id>`  | `shardcloud app status <app_id>`                                                              |
| `shardcloud logs <app_id>`    | `shardcloud app logs <app_id>`                                                                |
| `shardcloud start <app_id>`   | `shardcloud app start <app_id>`                                                               |
| `shardcloud stop <app_id>`    | `shardcloud app stop <app_id>`                                                                |
| `shardcloud restart <app_id>` | `shardcloud app restart <app_id>`                                                             |
| `shardcloud delete <app_id>`  | `shardcloud app delete <app_id>`                                                              |
| `shardcloud backup <app_id>`  | `shardcloud backup create <app_id>` — and now also works for databases and VMs, not just apps |
| `shardcloud restore <app_id>` | `shardcloud backup restore <app_id> <backup-id>` — also works for databases and VMs           |

## Examples

For detailed examples of using every command with resource IDs and from linked directories, see the [Commands](/cli/commands) reference.