CLI

@truetick/cli is the truetick command — a thin, scriptable wrapper over the API. It does double duty: a plugin/mod dev-loop (init → deploy → dev → down) and full server management (servers, files, backups, mods, console, logs, wallet).

Install

npm install -g @truetick/cli      # then: truetick <command>
# or, no install:
npx @truetick/cli servers list

Log in

truetick login                       # device flow (opens a browser)
truetick login --key ttk_your_key    # paste a key from the dashboard
truetick login --email you@x.com --password   # mint a key (prompts if value omitted)

Credentials save to ~/.truetick/config.json (mode 0600). truetick logout removes them. See Authentication for the flows in detail.

Global flags & env. Add --json to any command for raw JSON output. TRUETICK_API_KEY overrides the saved key; TRUETICK_API_URL overrides the base URL (default https://api.truetick.gg).

Onboarding & account

Command	What it does
`truetick signup --email <e> [--password <p>] [--url <baseUrl>]`	Create an account and save a key
`truetick login [--key <ttk>] [--email <e>] [--password <p>] [--url <baseUrl>]`	Log in (key paste / password / device flow). A password or device login mints a key only for an account you own, and at the 25-key cap revokes the `cli@…` key unused the longest: details
`truetick logout`	Remove saved credentials
`truetick whoami`	Show the account the key is bound to
`truetick wallet`	Show wallet balance
`truetick topup --amount <usd>`	Open a Paddle checkout and wait for the balance to update

Servers

truetick servers list
truetick servers get <id>                 # server record: state, plan, version — no tick data
truetick servers metrics <id>             # live TPS/MSPT/players (CLI 0.2.0+)
truetick servers tick-history <id> --hours 24   # one-minute buckets of tick health (CLI 0.2.0+)
truetick servers start <id>
truetick servers stop <id>
truetick servers restart <id>
truetick servers delete <id> --yes        # destructive — requires --yes

Create a server:

truetick servers create --name "My SMP" --ram 4096 --type PAPER --version 1.21.1 [--region na] [--plan metered]

Flag	Notes
`--name <name>`	Required. Slugified into the server id/hostname
`--ram <mb>`	Required unless `--template` is used
`--type <type>`	Core: `PAPER`, `PURPUR`, `VANILLA`, `FABRIC`, `FORGE`, …
`--version <v>`	Minecraft version, e.g. `1.21.1`
`--region <r>`	`na` or `eu`
`--plan <plan>`	`metered` (default) or `flat`
`--template <id>`	Create from a template; `--ram`/`--region`/`--version`/`--plan` become overrides

Create from a template instead of bare inputs:

truetick templates list
truetick servers create --template paper-survival --name "my-server"

Console (RCON)

truetick console <id> "say Hello from the CLI!"

Logs

truetick logs <id> --tail 100      # snapshot of recent lines
truetick logs <id> --follow        # live stream (Ctrl-C to stop)

See Stream logs.

Files

truetick files ls  <id> /data
truetick files cat <id> /data/server.properties
truetick files put <id> /data/ ./local.txt     # SFTP upload, binary-safe (jars OK)
truetick files rm  <id> /data/old.txt --yes    # destructive — requires --yes

files put uploads over per-server SFTP, so it's safe for binary artifacts. If the remote path ends in / (or is empty), the local filename is appended. Each files put, and each deploy, issues a new SFTP password for the server, and the previous one stops working, a login saved in an SFTP client included. To add a plugin jar without that, use Upload .jar in the panel (up to 100 MB).

Backups

truetick backups create  <id>
truetick backups list    <id>
truetick backups restore <id> <backupId> --yes   # server must be stopped; requires --yes

Mods

truetick mods list   <id>
truetick mods add    <id> --source modrinth   --project chunky [--version <version-number-or-id>]
truetick mods add    <id> --source curseforge --project 360438 [--version <file-id>]
truetick mods remove <id> --source modrinth   --project chunky

chunky has Modrinth builds for Paper and for the mod loaders; 360438 is the CurseForge project ID of Lithium, a Fabric and NeoForge mod. On CurseForge, --version takes a numeric file ID. What an add brings along and which adds are refused: Mods & modpacks.

The dev-loop

For plugin/mod authors. init writes truetick.toml, deploy builds-uploads-restarts-confirms, dev does that on every rebuild, down deletes the dev server that init --create made — since CLI 0.2.0, only a server that truetick.toml marks ephemeral = true (see the warning below).

cd my-plugin
 
# Bind to an existing server…
truetick init --server my-smp
# …or create a fresh metered, scale-to-zero dev server (requires --yes for the metered charge):
truetick init --create --name "Dev" --ram 4096 --type PAPER --yes
 
truetick deploy          # build → upload jar (SFTP) → restart → confirm it loaded
truetick deploy --no-build   # skip the build step
truetick dev             # redeploy on every artifact change + tail logs (Ctrl-C to stop)
truetick down --yes      # delete the dev server; 0.2.0+ deletes only one truetick.toml marks ephemeral

⚠️

down deletes only a server that truetick.toml marks ephemeral = true, which init --create writes for the server it made. init --server writes ephemeral = false, and down refuses that server, with or without --yes: deleting a real server takes its world, files and backups with it, so that takes the explicit truetick servers delete <id> --yes.

That is CLI 0.2.0 and later. CLI 0.1.x deletes whatever truetick.toml names once you pass --yes, a --server binding included, after only a warning, and it accepts init --server together with --create, which marks the bound server ephemeral = true. down goes by that flag alone, so 0.2.0 deletes a real server such a file names: if you ever ran init --server <id> --create on 0.1.x, set ephemeral = false in truetick.toml by hand before you use down, or run truetick init --server <id> again. The re-run rewrites the whole file with ephemeral = false: target, build and artifact are detected again and on_deploy goes back to restart, so re-apply any change you made to them. npm ls -g @truetick/cli shows the version you have; npm install -g @truetick/cli@latest updates it.

init flags: --server <id>, or --create with --name, --ram (default 4096), --type, --version, --region, --yes. Since CLI 0.2.0 init refuses --server and --create together, before it reads or creates anything. A --create server is metered + scale-to-zero — you're billed only while it's awake. Full recipe: Deploy a plugin.

`truetick.toml`

init auto-detects your build and writes the project file:

Field	Meaning
`server`	Server id this project deploys to
`target`	Upload dir: `plugins` (Bukkit cores) or `mods` (loaders)
`build`	Build command (Gradle → `gradle build`, Maven → `mvn -q package`); omitted if undetected
`artifact`	Glob for the built jar (e.g. `build/libs/.jar`, `target/.jar`, `*.jar`)
`on_deploy`	`restart`
`ephemeral`	`true` when created by `init --create`; `init --server` writes `false`. Since CLI 0.2.0, `down` deletes only an `ephemeral = true` server

server = "dev"
target = "plugins"
build = "gradle build"
artifact = "build/libs/*.jar"
on_deploy = "restart"
ephemeral = true

Destructive commands

Anything that deletes or overwrites data requires an explicit --yes; without it the command refuses:

Refusing destructive action without --yes: Delete server my-smp?

This covers servers delete, files rm, backups restore, and down. Since CLI 0.2.0, down also refuses, even with --yes, a server that truetick.toml doesn't mark ephemeral = true; 0.1.x deletes it after a warning — see the dev-loop.

TypeScript SDK MCP server