# SimpleCloud CLI

> Run your SimpleCloud network from the terminal. Every prompt has a flag, so scripts and AI agents can run it too.

`sc` (also installed as `simplecloud`) manages the same network as the [dashboard](https://dash.simplecloud.app). This page describes v0.0.1-beta.101.

## Install

Script:

```bash
curl -fsSL https://get.simplecloud.app | bash
```

npm:

```bash
npm i -g simplecloud
```

bun:

```bash
bun add -g simplecloud
```

macOS and Linux. The script installs Bun if it is missing.

Then run `sc setup` on the machine that should host your servers. In a terminal it opens a full-screen setup; with flags it runs without one:

```text
$ sc setup --network my-network --host-name eu-1 --max-memory 80% --runner tmux --start

ϟ simplecloud setup · v0.0.1-beta.101

✓ Dependencies ready
✓ Connected to My Network
✓ Downloaded serverhost  v0.0.1-beta.96  4.2s
✓ Registered eu-1
✓ Installed in ~/simplecloud
✓ Started serverhost  1.6s

eu-1 is ready in 9.8s

Next
  sc status             Check the serverhost
  sc logs serverhost    Show its log
```

## Commands

The same groups as `sc --help`. `sc <command> --help` lists every flag; do not guess them.

### Get started

#### sc setup

Set up a serverhost on this machine.

```bash
sc setup --network my-network --yes
sc setup
sc setup --network my-network --host-name eu-1 --max-memory 80% --runner tmux --start --json
```

#### sc login

Sign in with a device code.

```bash
sc login --no-browser
sc login
sc login --force
```

#### sc status

Show whether this serverhost is running.

```bash
sc status --json
sc status
```

### Network

#### sc group

Create, scale and roll out server groups.

```bash
sc group rollout restart lobby
sc group list --type proxy
sc group create lobby --software paper --configurator paper_velocity --yes
sc group update lobby --scaling-max 4 --deployment-host eu-1 eu-2
sc group start minigames --wait
```

#### sc group plugin

Add plugins from Modrinth, Spigot or a URL.

```bash
sc group plugin add lobby mr:luckperms
sc group plugin list lobby
sc group plugin remove lobby luckperms
```

#### sc server

List servers, read their logs, stop them.

```bash
sc server logs lobby 1 --follow
sc server list --group lobby
sc server info lobby 1
sc server logs lobby 1 --severity ERROR --search timeout
sc server stop lobby 1-3 proxy 1
```

#### sc persistent-server

Servers that keep their world, like SMP.

```bash
sc persistent-server list
sc persistent-server create survival --software paper --configurator paper_velocity --yes
sc persistent-server info survival --json
```

#### sc blueprint

Software, version and Java of a group.

```bash
sc blueprint update lobby --java-version 21
sc blueprint list
sc blueprint update lobby --software-version 1.21.4
```

#### sc serverhost

Add, verify and delete machines.

```bash
sc serverhost list
sc serverhost add --network my-network --install-dir ./eu-2 --host-name eu-2
sc serverhost delete eu-2 --yes
```

#### sc file

Read, edit and upload files on any server.

```bash
sc file tail ps:survival:/logs/latest.log -n 200
sc file targets
sc file ls templates:/Lobby -d 3
sc file edit ps:survival:/server.properties --old max-players=20 --new max-players=50
sc file upload ./plugin.jar Lobby/plugins/plugin.jar --templates
```

#### sc network

Register a network and check its credentials.

```bash
sc network verify
```

### This machine

#### sc start, stop, restart

Start and stop the serverhost.

```bash
sc restart serverhost --no-stop-servers
sc start
sc start serverhost --update
sc stop --no-stop-servers
```

#### sc logs, attach

Read the serverhost's log or open its console.

```bash
sc logs serverhost -n 50
sc attach serverhost
```

#### sc install

Install Java, PostgreSQL and other services.

```bash
sc install java 21
sc install service postgresql --instance players --set database=players
sc install serverhost --jar ./build/libs/serverhost.jar
```

#### sc upgrade, repair

Update or reinstall the CLI and serverhost.

```bash
sc upgrade serverhost@0.0.50
sc upgrade
sc repair
```

#### sc sync

Keep templates in sync across serverhosts.

```bash
sc sync status
sc sync init
sc sync add
```

#### sc local

Find and stop stuck Java processes.

```bash
sc local cleanup --name lobby
sc local cleanup
```

### Account

#### sc context

Switch between networks.

```bash
sc server list --context production
sc context list
sc context add staging --network my-staging-network
sc context use staging
```

#### sc whoami, logout, config

Your account and CLI settings.

```bash
sc config show
sc whoami
sc logout
```

#### sc completion

Tab completion for bash, zsh, fish and PowerShell.

```bash
sc completion zsh > ~/.zsh/completions/_sc
```

## Agents and scripts

Every question sc asks has a flag. Without a terminal, or with `SC_NON_INTERACTIVE=1`, a missing answer fails at once with a `missing_input` error that names the flag. sc does not read answers piped into stdin.

```text
$ sc group create --software paper --json
{"error":{"code":"missing_input","message":"Missing --name: \"Name\" needs an answer and no terminal is available","details":"Pass --name, or run the command in an interactive terminal.","flag":"--name"}}
$ echo $?
1
```

- `--json`: Results on stdout, progress on stderr.
- `--yes`: Skips confirmations.
- `--wait`: Returns once the server is running.
- `--no-browser`: Prints the sign-in code instead of opening a browser.
- `--network`: Picks the network for one call.

With `--json` (or `SC_OUTPUT=json`), an error is one JSON object on stderr with a `code`: `usage`, `missing_input`, `not_found`, `conflict`, `precondition_failed`, `unauthorized`, `unavailable`, `timeout`, `too_large`, `error`. A failed controller request adds its HTTP `status`. The exit code is 0 on success, 1 on failure, and 130 or 143 after Ctrl+C or SIGTERM.

Ask the user before you stop or delete servers, groups or serverhosts.

## sc vs. the console

SimpleCloud v2, CloudNet and other clouds are run from a console in screen. The prompt you type commands into after starting the cloud: the manager in SimpleCloud v2, the node in CloudNet, the core in TimoCloud. It usually runs in screen or tmux.

| | sc | The console |
| - | - | - |
| Where it runs | Any machine you are signed in on. | On the machine it runs on, over SSH. |
| Several people | Each in their own shell. | Everyone types into the same screen. |
| Output | Tables, or JSON with `--json`. | Log lines in the scrollback. |
| Scripts and agents | Flags and exit codes. | Keystrokes sent into screen. |

Need a console anyway? `sc attach serverhost` opens one, and the dashboard has one for every server. See the [CloudNet comparison](https://simplecloud.app/compare/cloudnet-v4).

## More

- [CLI guide](https://simplecloud.app/docs/en/manual/introduction/architecture/cli)
- [Installation guide](https://simplecloud.app/docs/en/manual/setup/installation)
- [Site index](https://simplecloud.app/llms.txt)
- [Agent guide](https://simplecloud.app/AGENTS.md)
- [OpenAPI spec](https://simplecloud.app/openapi.json)
- [Docs MCP server](https://simplecloud.app/.well-known/mcp/server-card.json)