Commands - Shard Cloud

Make sure you are authenticated before proceeding.

Commands that take a resource ID accept it as an argument, e.g. shardcloud app restart <id>. If you omit the ID and the current directory is linked to that resource type, the CLI uses the linked resource. If neither is given, the command fails with a clear error — unlike v1, there is no interactive selection menu to pick from your resources.

Linking a Directory

A link ties the current directory to one existing app, database, or VM, so you can omit the ID on every subsequent command run from that directory. It’s stored in a .shardcloud.json file:

{
  "resource_id": "550e8400-e29b-41d4-a716-446655440000",
  "resource_type": "app"
}

shardcloud link <id> --type app       # or: database, vm
shardcloud unlink                     # removes .shardcloud.json from the current directory

.shardcloud.json (the directory link) is separate from .shardcloud (the app’s own build/deploy config file) — linking a directory doesn’t touch your .shardcloud file, and vice versa.

shardcloud app create auto-links the directory it’s run from to the newly created app, the same way v1’s create did — you don’t need to run shardcloud link yourself right after creating an app. Databases and VMs have no creation-time side effect to piggyback a link off of (databases are created with db create, VMs only from the dashboard), so link those with shardcloud link <id> --type database / --type vm after the fact if you want to omit their ID from a directory.

`auth` / `config`

See Authentication for auth login / auth logout / auth whoami and config profile *. config set <key> <value> sets a free-form CLI setting — currently used for api_url, to point the CLI at a different API base URL:

shardcloud config set api_url https://staging.shardcloud.app/api

`app`

app has an apps alias — shardcloud apps list works the same as shardcloud app list.

Command	Args	Key flags	Description
`create`	-	`--file`, `--from-image`, `--ram`, `--name`	Create a new app
`list`	-	-	List your apps
`get`	`[id]`	-	Show one app’s details
`delete`	`[id]`	`-y, --yes`	Delete an app
`start`	`[id]`	-	Start a stopped app
`stop`	`[id]`	-	Stop a running app
`restart`	`[id]`	-	Restart an app
`status`	`[id]`	`--watch`	Show an app’s live status
`logs`	`[id]`	`--since`, `--http`	Stream an app’s logs
`metrics`	`[id]`	`--minutes` (default 60)	Show resource metrics
`commit`	`[id]`	`--file`	Deploy the current directory (or a zip) to an app
`deploys list`	`[id]`	-	List an app’s deploy history
`deploys restore`	`<deploy-id> [id]`	-	Restore an app to a previous deploy
`resize`	`[id]`	`--ram` (required)	Change an app’s RAM allocation
`rename`	`[id]`	`--name` (required)	Rename an app
`version set`	`[id]`	`--language`, `--version` (required)	Set the app’s language version
`version list`	-	`--language` (required)	List available versions for a language
`web enable`	`[id]`	`--subdomain`	Enable public web access
`web disable`	`[id]`	-	Disable public web access
`env list`	-	`--app`	List environment variables
`env set`	`KEY=VALUE...`	`--app`	Set one or more environment variables
`env pull`	-	`--app`	Write env vars to a local `.env` file
`env run`	`-- <command>`	`--app`	Run a local command with the app’s env vars injected
`exec`	`[id] -- <command>`	-	Run a command inside the app’s container

Create

# Zip and deploy the current directory
shardcloud app create

# Deploy a pre-built zip instead of zipping the cwd
shardcloud app create --file dist.zip

# Deploy from a custom Docker image (requires --name and --ram)
shardcloud app create --from-image <image-id> --name my-api --ram 512

create always writes a .shardcloud.json link to the current directory pointing at the new app, whichever path you use.

Deploys

app deploys list and app deploys restore only return data for apps linked to a GitHub repository. Apps deployed via zip upload (shardcloud app commit) have no deploy history to list or restore from these commands.

Env

shardcloud app env list --app <id>
shardcloud app env set DATABASE_URL=postgres://... DEBUG=true
shardcloud app env pull                        # writes ./.env
shardcloud app env run -- npm run start        # runs locally with the app's env injected

env set merges into the app’s existing variables — it doesn’t wipe ones you don’t mention. All env subcommands accept --app <id> in place of a positional ID/link.

Exec

shardcloud app exec <id> -- npm run migrate

Streams stdout/stderr live and exits with the remote command’s exit code.

`db`

db has database/databases aliases.

Command	Args	Key flags	Description
`create`	-	`--type`, `--name`, `--ram` (all required), `--password`	Create a new database
`list`	-	-	List your databases
`get`	`[id]`	-	Show one database’s details
`delete`	`[id]`	`-y, --yes`	Delete a database
`start`	`[id]`	-	Start a stopped database
`stop`	`[id]`	-	Stop a database
`status`	`[id]`	-	Show a database’s replica status
`metrics`	`[id]`	`--minutes` (default 60)	Show resource metrics
`password set`	`[id]`	`--password`, `--generate`	Change the database password
`connection-url`	`[id]`	`--copy`	Show (or copy) the connection URL
`resize`	`[id]`	`--ram` (required), `--vcpu`	Change RAM/vCPU
`visualizer enable`	`[id]`	-	Enable the database’s visualizer UI

shardcloud db create --type postgres --name mydb --ram 512
# --password omitted above: the CLI generates and prints a random one

shardcloud db connection-url <id> --copy
shardcloud db password set <id> --generate

--type accepts postgres, mysql, mongo, or redis.

`vm`

vm has a vms alias. shardcloud vm create does not exist. VMs are created from the web dashboard only — creating one starts a real recurring subscription charge, so the CLI deliberately doesn’t expose a way to trigger that. Every other vm command works once a VM exists.

Command	Args	Key flags	Description
`list`	-	-	List your VMs
`get`	`[id]`	-	Show one VM’s details
`delete`	`[id]`	`-y, --yes`	Delete a VM (also cancels its recurring charge)
`start`	`[id]`	-	Start a VM
`stop`	`[id]`	-	Stop a VM
`ssh`	`<id>`	-	SSH into a VM (shells out to your system `ssh`)
`exec`	`<id> -- <command>`	`--cwd`	Run a command on a VM over exec (not a full shell)
`password set`	`[id]`	`--password`, `--generate`	Change the VM’s root password
`reinstall`	`[id]`	`--distro`, `--password`, `-y, --yes`	Wipe and reinstall a VM
`resize`	`[id]`	`--ram` (required)	Change a VM’s RAM allocation
`metrics`	`[id]`	`--watch`, `--minutes` (default 60)	Show resource metrics
`distros list`	-	-	List available VM distros
`templates list`	-	-	List available VM templates

shardcloud vm ssh <id>
shardcloud vm exec <id> --cwd /opt/app -- ls -la
shardcloud vm reinstall <id>

vm reinstall --distro is accepted by the CLI but ignored by the backend — a reinstall always reuses the VM’s current distro, there is no API to change it. The CLI prints a note to stderr when you pass --distro so you aren’t left wondering why the distro didn’t change.

`backup`

Generic across apps, databases, and VMs — the same commands work for all three resource types, since it’s one backup API underneath.

Command	Args	Key flags	Description
`create`	`<resource-id>`	`--target-database`, `--name`	Create a backup
`list`	`<resource-id>`	-	List backups
`restore`	`<resource-id> <backup-id>`	`--target-database`, `-y, --yes`	Restore a backup
`delete`	`<resource-id> <backup-id>`	`-y, --yes`	Delete a backup
`download`	`<resource-id> <backup-id>`	`-o, --output`	Download a backup

shardcloud backup create <app-id> --name pre-deploy
shardcloud backup list <db-id>
shardcloud backup restore <vm-id> <backup-id>
shardcloud backup download <app-id> <backup-id> -o backup.tar.gz

--target-database is only relevant when backing up/restoring a database resource. download without -o/--output prints the backup’s download URL instead of saving it.

`lb`

Load balancers require a Pro or Enterprise plan. Creating one, or claiming a domain for one, on a lower plan fails with a plan-tier error.

A load balancer is a named, reusable pool of sibling apps that a domain can point at, so traffic round-robins/fails over across them instead of being tied to one app.

Command	Args	Key flags	Description
`create`	-	`--name` (required)	Create a load balancer
`list`	-	-	List your load balancers
`get`	`<id>`	-	Show one load balancer’s details
`delete`	`<id>`	`-y, --yes`	Delete a load balancer
`update`	`<id>`	`--timeout-ms`	Update proxy timeout
`target add`	`<id> <app-id>`	`--group`	Add a target app
`target remove`	`<id> <app-id>`	-	Remove a target app
`target enable`	`<id> <app-id>`	-	Enable a target app
`target disable`	`<id> <app-id>`	-	Disable a target app
`target group set`	`<id> <app-id>`	`--group` (required)	Set a target’s host-rule group

shardcloud lb create --name main
shardcloud lb target add <lb-id> <app-id> --group api
shardcloud lb update <lb-id> --timeout-ms 30000

lb (and its aliases loadbalancer/loadbalancers) has no domain or error-page subcommands — claiming a custom domain for a load balancer is done from the web dashboard, not the CLI.

`image`

Custom Docker images: build them from a directory or zip, then deploy them as apps.

Command	Args	Key flags	Description
`build`	-	`--context` (default `.`), `--name` (required)	Build a new custom image
`list`	-	-	List your custom images
`get`	`<id>`	-	Show one image’s details
`rebuild`	`<id>`	`--context` (default `.`)	Rebuild an image from a new build context
`delete`	`<id>`	`-y, --yes`	Delete a custom image
`logs`	`<id>`	`--follow`	Stream an image’s build logs
`deploy`	`<image-id>`	`--name`, `--ram` (required), `--env`	Deploy a built image as a new app

shardcloud image build --name my-image --context .
shardcloud image deploy <image-id> --name my-api --ram 512 --env PORT=3000 --env NODE_ENV=production

--context accepts either a directory (zipped Docker-context-aware, honoring .dockerignore and keeping the Dockerfile) or a path to an existing .zip.

image rebuild always requires a build context (--context, defaulting to the current directory) — there is no “reuse the previous build’s context” option. Every rebuild re-packs and re-uploads a context from scratch.

Misc

Command	Description
`version`	Print the CLI version
`update`	Check for a newer CLI version and print the right upgrade command
`completion`	Generate shell completions (bash, zsh, fish, powershell)
`docs <topic>`	Open a docs page in your browser (`apps`, `databases`, `vms`, `domains`, `config`, `cli`, `cdn`)

shardcloud completion zsh > ~/.zsh/completions/_shardcloud
shardcloud docs vms

​Linking a Directory

​auth / config

​app

​Create

​Deploys

​Env

​Exec

​db

​vm

​backup

​lb

​image

​Misc

Linking a Directory

`auth` / `config`

`app`

Create

Deploys

Env

Exec

`db`

`vm`

`backup`

`lb`

`image`

Misc