CLI Reference

By the end of this page you will be able to do anything the interface does from a shell script or a CI job.

Invocation#

osmium [command] [flags]

Running osmium with no command opens the full-screen interface. Every other command does one thing and returns.

Global flags#

--server is what makes Osmium scriptable from anywhere. Leave it out and the command acts on the folder you are standing in, so you can cd into a server and type osmium logs -f. Names are matched case-insensitively, and a server's folder name works as well as its registered name.

A command that needs a server and finds neither says so rather than guessing.

Exit codes#

How the CLI and the TUI share state#

They are one binary over one set of files. The registry of servers, config.json, each server's osmium.json and osmium.lock, and the download cache are read and written by both.

A running server belongs to neither: it is held by a detached supervisor process that owns its stdin and writes its output to .osmium/server.log. That is why osmium exec reaches a server started from the interface, a previous shell, or a login that has since ended — and why closing Osmium never stops a server.

---

Server lifecycle#

osmium create#

osmium create [flags]

Creates a server: downloads the jar for the engine and version you pick, writes osmium.json, accepts the EULA and registers the result. Anything given as a flag is taken as answered; whatever is left is asked for, one prompt at a time. Give every flag and nothing is asked at all, which is what makes this scriptable.

--from rebuilds a server from a manifest — the osmium.json of an existing server, or the one osmium destroy kept. The engine, version and memory come from it, and every mod and plugin it lists is installed into the new server. Flags given on the command line win over the manifest.

$ osmium create -n Survival -e Fabric -v 1.21.1 --ram 6G --eula
Created Survival in /home/you/.config/osmium/servers/Survival

See also: osmium install to build from a recipe, osmium destroy to remove one.

osmium list#

osmium list
osmium ls

Shows every server Osmium knows about: what it runs, where it lives and whether it is up right now. The names in the first column are what --server takes.

This command has no flags of its own.

$ osmium list
NAME      ENGINE  VERSION  MEMORY  STATE              PATH
survival  PAPER   1.21.1   4G      running (pid 8821) /home/you/minecraft/survival
creative  FABRIC  1.20.4   6G      stopped            /home/you/minecraft/creative

missing in the state column means the folder is no longer there.

See also: osmium details.

osmium details#

osmium details [flags]
osmium info [flags]

Prints what a server is, what it is doing and who is on it: its engine and version, where it lives and how much disk it takes, its players, ops and bans, and how many mods and plugins it has.

Online players are asked of the server's own status port, the way the game's server list asks, so they only appear while it is running and nothing is typed into the console — running this leaves no trace in the log.

$ osmium details -s survival
survival
  state         running (pid 8821)
  memory        4G
  engine        Paper 1.21.1
  folder        /home/you/minecraft/survival
  running       1.21.1 (3 ms)
  motd          A Minecraft Server
  size on disk  412 MB
  mods          0
  plugins       3
  online        2 / 20  Steve, Alex
  ops           Steve
  banned        -
  whitelisted   -
  known         7 players seen

See also: osmium list, osmium doctor.

osmium start#

osmium start [flags]

Starts a server under a supervisor process of its own. The server keeps running after this command returns and after Osmium's interface is closed.

$ osmium start --server survival --follow
Started survival.
server │ Starting minecraft server version 1.21.1

See also: osmium stop, osmium logs, osmium exec.

osmium stop#

osmium stop [flags]

Asks a server to shut down the way the console stop command does, so it saves its world on the way out, and waits until it is really down.

--force does not save the world. Reach for it only when a server has stopped responding.

$ osmium stop -s survival
survival is shutting down....
Stopped.

See also: osmium restart.

osmium restart#

osmium restart [flags]

Stops a running server, waits for it to finish saving, and starts it again. A server that is not running is simply started.

$ osmium restart -s survival
survival is shutting down...
Stopped.
Started survival.

If the server does not stop within 90 seconds it is not restarted, and the command says so rather than starting a second one on top of it.

osmium exec#

osmium exec <minecraft command…> [flags]

Sends a command to a running server, exactly as if it had been typed into the server console. The server is reached through its supervisor, so this works whoever started it.

$ osmium exec -s survival say the server restarts in 5 minutes
Sent to survival: say the server restarts in 5 minutes

Quote anything the shell would otherwise take apart: osmium exec -s survival "time set day".

See also: osmium logs.

osmium logs#

osmium logs [flags]

Prints what a server has said, and optionally keeps printing as it says more. Each line is labelled with where it came from — the server itself, Osmium, a mod operation, or a command someone typed — so the sources stay apart.

$ osmium logs -s survival -n 3
osmium │ starting Paper 1.21.1
server │ Done (12.481s)! For help, type "help"
you    │ say hello

ctrl+c stops following. It does not stop the server.

osmium destroy#

osmium destroy [flags]

Deletes a server's folder — world included — and removes it from the list. This cannot be undone, so it asks you to type the server's name first.

--keep-manifest and --delete-everything cannot both be given. A running server is refused unless --force is passed, which stops it first.

Keeping the manifest is worth doing: it records the loader, version, memory and every tracked mod, so the same server can be built again from it with osmium create --from.

$ osmium destroy --server old-test --keep-manifest
This deletes /home/you/minecraft/old-test and everything inside it, world included.
Type the server's name (old-test) to confirm: old-test
Deleted old-test (/home/you/minecraft/old-test).
Kept its manifest at /home/you/minecraft/old-test.osmium.json - rebuild from it with 'osmium create'.

See also: osmium create, osmium backup.

---

Mods and plugins#

osmium mod … manages mods/; osmium plugin … is the same set of subcommands for plugins/. Which one your server takes follows from its server software: Paper, Purpur, Spigot, Bukkit and Folia take plugins, and everything else takes mods.

Every subcommand works the whole change out first — including anything a mod depends on — shows it, and applies it in one go. Nothing is written until every file has arrived and been checked against the SHA-1 Modrinth publishes, so a failure halfway through leaves the server as it was. Files are kept in a shared cache by their content, so the same mod wanted twice is downloaded once.

What is asked for is recorded in osmium.json; what that resolved to is recorded in osmium.lock.

Flags shared by the changing subcommands#

These are on add, remove, install, update, pin and unpin:

The plan is always printed. You are asked to confirm only when something would be lost.

osmium mod add#

osmium mod add <project>[@build] … [flags]

Installs one or more projects and whatever they need. Projects are named by their Modrinth slug. name@build holds it at one build, which is a pin.

$ osmium mod add spectrum -s survival
2 to install, 1 to add as a dependency

  + spectrum    1.10.5   asked for
  + fabric-api  0.102.0  needed by spectrum
  + owo-lib     0.12.6   needed by spectrum

See also: osmium mod search, osmium mod versions, osmium mod pin.

osmium mod remove#

osmium mod remove <project> … [flags]

Removes projects, and anything left over that nothing else needs. Jars Osmium did not install are never touched.

$ osmium mod remove spectrum -s survival
1 to remove, 2 no longer needed

  - spectrum    1.10.5
  - owo-lib     0.12.6   needed by nothing
  - fabric-api  0.102.0  needed by nothing

Continue? [Y/n]

osmium mod list#

osmium mod list [flags]
osmium mod ls [flags]

Lists what is installed, which build, and why it is there.

$ osmium mod list -s survival
NAME        BUILD    WHY                 FILE
fabric-api  0.102.0  needed by spectrum  fabric-api-0.102.0+1.21.1.jar
sodium      0.5.8    pinned              sodium-fabric-0.5.8+mc1.21.1.jar
spectrum    1.10.5   asked for           spectrum-1.10.5.jar

Jars in the folder that Osmium does not manage are listed underneath, with the command that adopts them.

osmium mod install#

osmium mod install [flags]

Installs exactly what the manifest and lock describe. This is the command for a folder that has the two files but not the jars — a fresh clone, or a server that has lost files.

$ osmium mod install -s survival
3 to install

  + fabric-api  0.102.0  needed by spectrum
  + sodium      0.5.8    pinned
  + spectrum    1.10.5   asked for

See also: osmium install, which does this for a whole server including the engine.

osmium mod update#

osmium mod update [project …] [flags]

Moves projects to their newest builds, leaving pinned ones alone. Name projects to update only those; name none to update everything that is not pinned.

$ osmium mod update -s survival
1 to update

  ↑ fabric-api  0.102.0 → 0.105.0  needed by spectrum

See also: osmium mod pin, osmium migrate.

osmium mod pin#

osmium mod pin <project>[@build] [flags]

Holds a project at one build until it is unpinned. Given a build, it moves there and stays; given none, it stays where it is.

$ osmium mod pin sodium@0.5.8 -s survival
1 to pin

  = sodium  0.5.8  pinned

osmium mod unpin#

osmium mod unpin <project> [flags]

Lets a project move with the rest again. It does not change which build is installed; the next update does that.

$ osmium mod unpin sodium -s survival

osmium mod versions#

osmium mod versions <project> [flags]

Lists the builds this server could install — narrowed to its loader and its Minecraft version, so what is listed is what would actually work.

$ osmium mod versions sodium -s survival
BUILD   CHANNEL  SIZE
0.6.0   release  412 KB   newest
0.5.8   release  408 KB   installed
0.5.3   release  401 KB

osmium mod search#

osmium mod search <words> [flags]

Finds projects that fit this server. Up to fifteen results.

$ osmium mod search world edit -s survival
NAME        SLUG
WorldEdit   worldedit
FastAsyncWorldEdit  fastasyncworldedit

The slug in the second column is what add takes.

osmium mod track#

osmium mod track [flags]

Adopts jars already sitting in the folder — identifying each one by its hash and recording it in the lock, so Osmium manages it from then on.

$ osmium mod track -s survival
  + lithium  0.12.1  adopted

Jars it cannot identify are left alone and stay unmanaged.

---

Versions#

osmium migrate#

osmium migrate [flags]

Migrates a server to a different mod loader or Minecraft version. It replaces the server jar, migrates existing mods and plugins to compatible versions, keeps world data and configs intact, and moves incompatible mods and plugins to a backup folder.

The loader and the version are asked for one at a time when they are not given as flags, using the same steps the interface uses. A running server is refused — stop it first.

$ osmium migrate --server survival --loader Fabric --version 1.20.4

See also: Updating for what a migration does to your world and to pinned entries.

---

Config and rebuilding#

osmium install#

osmium install [manifest|modpack|url] [flags]

Builds a whole server from a recipe. With no argument it reads the osmium.json in the current folder. Given a path or a URL it reads that instead, and given a .mrpack it installs a Modrinth modpack. With --server it rebuilds a server Osmium already knows about, which is how a folder that has lost files is repaired.

What it does is what create does, from a file instead of from questions: downloads the engine, accepts the EULA, writes the run script, registers the server, then installs everything the recipe lists. Where there is an osmium.lock the exact builds it names are installed, so the same recipe gives the same server; where a build has since been withdrawn, that project is resolved again and the change is reported.

$ osmium install ./packs/skyblock.json --name skyblock
$ osmium install cobblemon.mrpack --name cobblemon
$ osmium install https://example.com/pack/osmium.json

See also: Configuration for what a recipe contains.

osmium edit#

osmium edit [flags]

Changes the settings Osmium keeps for a server: what it is called in the list, and how much memory it is started with. This is not migrate — the loader, the version and the mods are untouched. With no flags it prints what the server is set to now.

$ osmium edit --server survival --ram 8G
survival: memory 4G → 8G
It is running with the old amount until it is restarted.

See also: osmium migrate for changing what the server runs.

---

Maintenance#

osmium doctor#

osmium doctor [flags]

Looks a server over and reports what it finds: whether the Java on the path is the one this Minecraft version needs, whether the memory it is promised exists, whether its port is free, whether the licence has been accepted, and whether the files the lock names are actually there. Nothing is changed, and every finding says what to do about it.

$ osmium doctor -s survival
survival

  ✓ java     java 21, correct for 1.21.1
  ✓ memory   4G of 16G
  ✓ port     25565 is free
  ✓ eula     accepted
  ✕ files    2 of 5 jars the lock names are missing

this server has problems that will stop it working

It exits 1 when it found a problem, which makes it usable as a check in a script.

See also: osmium mod install to put missing jars back.

osmium backup#

osmium backup [label] [flags]
osmium backup list [flags]

Copies the parts of a server that cannot be downloaded again: its world folders, its manifest and lock, its settings, and who is opped, whitelisted or banned. Mods and the engine are left out — they are named in the lock and can be fetched — which is what keeps a backup small enough to take often.

Backups are kept in .osmium/backups inside the server, so moving the server moves them with it.

The server may be running, in which case the world is a few seconds behind. For an exact copy, stop it first, or run save-off and save-all in the console before taking one.

$ osmium backup -s survival before-1.21
✓ before-1.21-2026-09-05-1432   84 MB

$ osmium backup list -s survival
NAME                          SIZE   TAKEN
before-1.21-2026-09-05-1432   84 MB  2 minutes ago
2026-09-01-0900               81 MB  4 days ago

See also: osmium restore.

osmium restore#

osmium restore [name] [flags]

Restores a backup over the server, newest first when no name is given.

The server has to be stopped. Writing a world out from under a running server corrupts it.

$ osmium restore before-1.21-2026-09-05-1432 -s survival
Restoring before-1.21-2026-09-05-1432, taken 2 minutes ago.
This overwrites the world as it stands now.
Continue? [Y/n] y
✓ restored

osmium expose#

osmium expose [flags]

Says which addresses reach this server and whether anything answers on them.

--open asks the router to send the server's port through to this machine, which is what lets people outside your network join. That is a change to the router, not to this computer, and --off takes it back. Nothing is installed either way. The mapping lasts a day; run it again to renew it.

The port is read from the server's server.properties, so the server has to have been started at least once.

$ osmium expose -s survival --check
  this machine   127.0.0.1:25565      ✓ answers
  this network   192.168.1.42:25565   ✓ answers
  the internet   203.0.113.7:25565    ✕ no answer

osmium cache#

osmium cache
osmium cache clean

Says where Osmium keeps the files it has downloaded, and how much room they take. clean empties it.

Files are kept by their content, so the same mod wanted by a second server, by a reinstall, or by a migration back to a version installed last month is already there and costs no network at all. Nothing in the cache is needed to run a server; emptying it only means the next install downloads again.

$ osmium cache
/home/you/.cache/osmium
128 files   1.4 GB

$ osmium cache clean
Removed 128 files, 1.4 GB.

osmium completion#

osmium completion install [shell]
osmium completion bash|zsh|fish|powershell

Osmium completes server names, installed mods and plugins, Minecraft versions and engines as you type.

install writes the script into the directory your shell reads completions from and tells you what it did; the shell is taken from $SHELL unless one is named. The per-shell subcommands print the script to stdout instead, for placing it yourself.

$ osmium completion install
Installed zsh completion to /home/you/.zsh/completions/_osmium
Open a new shell and press tab after 'osmium '.

See also: Installation.

osmium tui#

osmium tui [flags]

Opens the full-screen interface, which is also what running osmium with no arguments does.

See also: The TUI.