Command line

The worldplane CLI

One binary, worldplane, for studios and for CI. Its studio commands call the control plane's API, so anything they do can also be done in the panel or with curl. worldplane --help and worldplane <command> --help print the same flags as this page; worldplane --version prints its version.

Stopping a zone, reading its status, usage, the audit log, members and keys have no command: use the panel or the API.

Install#

Sign in to the panel and download it from Engine integrations on your organisation's overview: Windows or Linux, x86-64. No subscription is needed for it. Put it in a folder on your PATH; on Linux, make it executable first:

chmod +x worldplane && sudo mv worldplane /usr/local/bin/
worldplane --version

CI downloads it with an API key (GET /v1/downloads/cli/{platform}):

curl -fOJ "https://app.worldplane.net/v1/downloads/cli/linux" -H "Authorization: Bearer $WORLDPLANE_KEY"
chmod +x worldplane

Signing in, and CI#

The studio commands find the control plane and their credentials in one of two ways:

• An API key, for CI: when WORLDPLANE_KEY is set (a wpk_... key from the panel's API keys), the CLI uses it with WORLDPLANE_URL, which must then be set too.
• A session, for people: otherwise, the session worldplane login kept.

export WORLDPLANE_URL=https://app.worldplane.net
export WORLDPLANE_KEY=wpk_...        # from your CI's secret store
worldplane build push --project mystudio/mygame --label "$CI_COMMIT_SHA" LinuxServer.zip
worldplane deploy mystudio/mygame/test <build id>

The session is kept in session.json in %APPDATA%\worldplane on Windows, or $XDG_CONFIG_HOME/worldplane (else ~/.config/worldplane) elsewhere, readable by its owner only on Unix. WORLDPLANE_CONFIG_DIR names another folder instead. A session lasts 30 days.

A command that the control plane refuses exits non-zero and prints the status and the control plane's reason, such as 402 Payment Required: this needs an active WorldPlane subscription....

worldplane login#

Signs a person in and keeps the session for later commands. It asks for the password without showing it, and for the authenticator's code when the account has one.

worldplane login --url https://app.worldplane.net --email you@studio.example

Accounts are made in the panel (or with POST /v1/accounts); the CLI has no sign-up.

worldplane logout#

Ends the session on the control plane and deletes the session file. If the control plane can't be reached, the file is still deleted. No flags.

worldplane tenant create#

worldplane tenant create mystudio --name "My Studio"

You become its owner. Needs a person's session: an API key can't make an organisation.

worldplane project create#

worldplane project create mystudio/mygame --name "My Game"

worldplane env create#

worldplane env create mystudio/mygame/test --region us-east-2 --map /Game/Maps/World \
  --max-servers 8 --size plus --budget 2 --sleep-after 15 --server-arg -MyGameFlag

Server capacity (the load one server carries) has no flag; it stays at 100 unless changed in the panel or the API.

worldplane env update#

Changes an environment's name, budget or zone; a running zone takes it at its next deploy. Only what you give changes. The region can't change.

worldplane env update mystudio/mygame/test --map /Game/Maps/Other --max-servers 12 --size max

With none of them it stops with nothing to change.

worldplane env secret#

An environment's secrets, which its servers get as {env:NAME} in their arguments. Names are 1 to 64 capitals, digits or _, starting with a letter; names starting with WP_ are WorldPlane's own. Values are up to 4 KiB.

worldplane env secret set mystudio/mygame/test API_TOKEN          # asks for the value, unshown
printf '%s' "$API_TOKEN" | worldplane env secret set mystudio/mygame/test API_TOKEN
worldplane env secret set mystudio/mygame/test API_TOKEN --from-file token.txt
worldplane env secret list mystudio/mygame/test
worldplane env secret delete mystudio/mygame/test API_TOKEN

worldplane build#

build push#

Uploads a zip of the packaged LinuxServer folder as a new build, and waits for its checks.

worldplane build push --project mystudio/mygame --label 0.4.1 LinuxServer.zip

On app.worldplane.net the archive goes straight to storage in parts (each tried three times); a control plane that takes archives itself gets it in one request. The CLI then waits, up to an hour, while the build is imaged and started once. It prints the build's id and the deploy command when the build is ready, and exits non-zero with the reason when it is rejected or failed.

build check#

Runs the control plane's checks on an archive, on your machine, before you upload it.

worldplane build check LinuxServer.zip
worldplane build check LinuxServer.zip --json

--json prints the decision as JSON (state, reason, digest, plugin). Without it, it prints the plugin version found, or exits non-zero with the reason it would be rejected.

worldplane deploy#

worldplane deploy mystudio/mygame/test 3f2a9c...

It returns once the zone has been started, and prints the zone's status.

worldplane check#

Checks an Unreal project for what it needs before it runs on WorldPlane, from its files only. Exits 1 when it finds errors. See checking a project for what it looks for.

worldplane check path/to/MyGame --fix

Local tools#

These run WorldPlane's own services on your machine, for development and testing. Studios on app.worldplane.net don't need them.