Goethe

Goethe command reference

Every goethe command and its options. For a walkthrough, see the user guide.

goethe <command> [options]
goethe <command> --help

Conventions

  • The model is a plain argument: goethe load qwen 27b, goethe unload qwen-27b. Give its id, an alias, or words from its name; when several models match, a menu asks which one (without a terminal, they are listed). --model <id> still works.
  • Every other value goes after its flag: goethe gpu --allow gpu0 gpu1. A value typed without its flag prints the corrected command instead of running anything.
  • Commands are grouped: what concerns the API is under goethe api (configure, manage, keys, allowlist, gateway, domain, learn, trace), and model housekeeping under goethe models (recommend, scan, config, alias). The older top-level forms such as goethe key still work and say where they moved.
  • GPUs are named as goethe gpu lists them: gpu0, gpu1, and so on. Flags that take GPUs accept several: --gpu gpu2 gpu3.
  • Model ids are Hugging Face repo names such as zai-org/GLM-5.3-Flash. Case doesn't matter, and the folder form zai-org__GLM-5.3-Flash works too. A mistyped id gets a suggestion.
  • Commands that list things accept --json for scripts.

Exit codes:

Code Meaning
0 Success
1 Error
2 Wrong usage
3 A confirmation was needed but there was no terminal to ask on; add --yes

Contents

  • Start and stop: goethe, start, up, status, down
  • Models: install, models, models recommend, models scan, models config, models alias, remove
  • Running models: load, unload, ps, logs
  • API access: api, api configure, api manage, api keys, api allowlist, api gateway, api domain, api learn, api trace, serve --public
  • GPUs and system: gpu, hw, doctor, update, uninstall, completion, --version
  • Platform: login, logout

Start and stop

goethe

On a terminal, plain goethe opens the home screen: the sections on the left (Models, API access, API keys, GPUs, Learning & traces, Platform, Done), their state and what can be done on the right, refreshed every 5 seconds. ↑↓ move, → opens a section, ← goes back, q leaves. Enter on a model loads or unloads it; the access, key, learning and trace rows run goethe api configure, goethe api manage, goethe api learn and goethe api trace in the normal terminal and come back on Enter; Enter on a GPU allows or denies it; the Platform rows run goethe login or goethe logout. Without a terminal, goethe prints the commands.

goethe start

Guided setup. Starts Goethe, then walks through three steps: install a model, serve it through the API, and configure who can reach it. An advanced mode does each part on its own. Without a terminal, it prints the equivalent commands. Step 3 offers only API keys that may call the model just served, and the advanced setup opens goethe api manage for keys.

goethe up

Starts Goethe and the API gateway, and starts them at every boot from now on. Models that were loaded last time come back.

Option Description
--no-boot Start now without turning on start at boot

goethe status

Whether Goethe is running, the API address, the names and ids of your API keys, and the public gateway while it is open (goethe serve --public). The last lines show the platform link (Linked (workspace X), Not linked, or Revoked) and, when linked, the last heartbeat (OK (2 s ago) or failing: <reason>).

goethe down

Stops Goethe and its models, and turns off start at boot. Loaded models come back on the next goethe up.

Option Description
--keep-engines Keep models serving while Goethe itself restarts

goethe service

Not listed in goethe --help: goethe up already turns on start at boot and goethe down turns it off. It stays for the restore setting.

Command Description
goethe service enable Start Goethe at boot
goethe service disable Don't start Goethe at boot
goethe service status Whether Goethe starts at boot
goethe service restore --on / --off Whether loaded models come back when Goethe starts

Models

goethe models recommend

The catalog models that fit the GPUs Goethe may use, grouped by the memory they take, with the GPUs they would load on and their download size.

Option Description
--json JSON instead of a table

goethe install <model or folder>

Downloads a model from Hugging Face, or registers a model folder on this machine. Models with optimised kernels for this GPU use them when the node is logged in (goethe login); otherwise goethe asks to log in or continues with SGLang. A model that cannot be served is refused before anything is downloaded.

Option Description
<model> A Hugging Face id (org/name), a local folder, or words from a catalog model's name such as glm flash
--load Load the model after installing it
--no-load Install only
--no-wait With --load, return without waiting until it's ready
--ctx <N> Default context length (default: the model's full context window; a load uses the largest that fits in VRAM)
--max-conc <N> Default number of requests served at the same time
--tp <N> Default number of GPUs to split it across (0: automatic)
--gpu <gpuN>... GPUs to load on
--trust-remote-code Allow Python code that ships with the model; only for models you trust
--hf-token Ask for a Hugging Face token, for gated or private models; used for this download only, never stored
--yes With --load, load next to other programs on the GPU without asking
--force Download again, or replace an existing install
--reset Forget this model's saved settings
--no-verify Skip checking the downloaded files
--name <id> Id for a local folder
--copy Copy a local folder instead of linking to it
--sglang-arg <flag> An extra engine option saved with the model

goethe models scan

Adds model folders you placed in Goethe's models folder yourself. It checks each one and asks before adding it; a folder that can't be served is named with the reason.

Option Description
--dir <folder> Only this folder
--yes Add every supported model without asking
--json JSON output

goethe models

Installed models, then catalog models, with whether each fits this machine and its size on disk. Alias: goethe list.

Option Description
--installed Only installed models
--available Only catalog models
--json JSON output

goethe models config <model>

Changes the default settings a model loads with.

Option Description
--ctx <N> Default context length (default: the model's full context window; a load uses the largest that fits in VRAM)
--max-conc <N> Default number of requests served at the same time
--tp <N> Default number of GPUs
--gpu <gpuN>... Default GPUs
--sglang-arg <flag> Add an engine option
--clear-sglang-args Remove the saved engine options

goethe remove <model>...

Unloads a model and deletes the files Goethe downloaded. For a folder you registered in place, it only unregisters it. If traces were recorded with the model, it asks whether to delete them too; the default is to keep them.

Option Description
--yes Don't ask; unload it first if it's loaded; keep its traces
--force Don't wait for requests in progress
--delete-traces Also delete the model's traces, without asking
--keep-traces Keep the model's traces, without asking

Running models

goethe load <model> [-- <engine options>]

Loads a model and waits until it answers. Goethe picks the GPUs and sizes the memory unless you choose.

Option Description
--gpu <gpuN>... GPUs to load on; several split the model across them
--tp <N> Number of GPUs to split it across
--ep <N> Expert-parallel size, for mixture-of-experts models
--ctx <N> Context length
--max-conc <N> Requests served at the same time
--replica Start another copy, to serve more traffic
--yes Load next to other programs on the GPU without asking
--force Load on busy GPUs without asking
--no-wait Return without waiting until it's ready
--json Print the instance as JSON
-- <options> Extra engine options, after --
goethe load zai-org/GLM-5.3-Flash --gpu gpu1
goethe load zai-org/GLM-5.3-Flash --gpu gpu0 gpu1 gpu2 gpu3 --ctx 65536
goethe load zai-org/GLM-5.3-Flash -- --chunked-prefill-size 4096

goethe unload

Stops a model. Requests in progress finish first.

Option Description
<model>... The models to stop, one argument each
--all Every loaded model
--force Stop right away

goethe ps

Running models with their GPUs, port, memory, restarts, requests in progress and speed.

Option Description
--json JSON output

goethe logs

Option Description
<model> A model's log (also takes an instance id)
-f, --follow Keep printing new lines
-n, --lines <N> Number of lines (default 100)
--daemon Goethe's own log
--gateway The API gateway's log
--prune Clean up old logs

API access

goethe api configure

Chooses who can reach the API: this machine only, a VPN or other private network (recommended), or a public address. For a VPN it lists the networks this machine is on, with the ranges each one reaches, and works with any VPN that has a network interface. It then asks whether to restrict access to specific IP addresses. The gateway follows the chosen interface: when its address changes, it moves within a few seconds, and while the interface has no address only this machine can connect.

Option Description
--mode local|vpn|public The access mode (asked when omitted)
--interface <name> The network interface to serve, such as wg0; needed without a terminal when there are several
--vpn-ip <ip> A fixed address of this machine instead of an interface
--allow <cidr> A client address or range to allow; repeatable
--yes Apply without questions

goethe api

The API address, how to authenticate, the models it serves, your API keys and a curl command to try it.

Option Description
--json JSON output

goethe api manage

A full-screen key manager in two columns, like ranger. The left column picks what to work on: + Create new key, Done, then your keys. The right column shows the hovered entry and is where things change. For a key it shows API key: with the key itself, its name and id (fixed), then what can change: the allowed models (Every model, or ticked models), the rate limit, the expiry, Save changes and Delete key. For + Create new key it is the same form with a name, ending in Create key.

Key In the left column In the right column
↑ ↓ (or k j) Move between entries Move between fields
→ (or l, Enter) Open the entry on the right; on Done, leave
← (or h, Esc) Back to the left; asks first when there are unsaved changes
Space Tick a model or Every model
Enter Edit a value in place (Enter keeps it, Esc cancels), save, create, or delete (press twice)
q Leave Leave at once; unsaved changes are not saved, and a note says so

On Rate limit or Expires, the bottom line shows the values they take: a whole number of requests per minute (0 for unlimited), and never, days such as 30d or a date such as 2027-01-31. Changes apply only when saved and reach the gateway on the next request. The screen is restored on leaving, and keys created in the session are printed then. Admin keys are made with goethe api keys --admin; scripts use goethe api keys, since the menu needs a terminal (at least 64×12).

goethe api keys

Lists API keys with their limits and today's usage, or creates or revokes one.

Option Description
--create <name> Create a key
--expires <when> Expiry: days from now such as 30d, or a date such as 2027-01-31
--rpm <N> Requests per minute (default 120, 0: unlimited)
--models <a,b> Only these models
--admin Admin key: health endpoints and every model
--raw Print only the key, for scripts
--revoke <key id>... Revoke keys, by the id goethe api keys shows
--json JSON output
goethe api keys --create my-app
goethe api keys --create ops --expires 90d --rpm 300 --admin
API_KEY=$(goethe api keys --create ci --raw)

goethe api allowlist

Lists the client addresses allowed to reach the API, or adds or removes one.

Option Description
--add <cidr>... Allow addresses or ranges, such as 203.0.113.7 or 192.168.1.0/24
--description <text> A note stored with the new entries
--remove <cidr>... Remove addresses or ranges

goethe models alias

Short model names for clients. Changing what an alias points to moves every client that uses it.

Option Description
--set <alias> The alias clients send as the model
--model <id> The installed model it points to
--remove <alias>... Remove aliases

goethe api trace [on | off]

Records every generation request and reply, grouped into sessions, as a corpus for training later. off stops recording and keeps the chosen keys; on resumes with them (every key the first time). Without on or off it shows what is recorded, the folder, its size and the free disk. Changes apply to the next request. The format is in traces.md.

Option Description
--key <name or id>... With on: add these keys to the ones recorded. With off: leave them out
--all-keys With on: record every key, clearing the chosen keys and exceptions
--dir <path> Folder for the traces (default ~/.goethe/traces)
--max-gb <N> Size limit: recording turns off when the folder reaches it (default 20). Works without on or off
--json JSON output
goethe api trace on
goethe api trace on --key my-app
goethe api trace off

goethe api learn [on | off]

Lets a session keep what context compaction would drop, in a small note that goes into the prompt after each compaction. Sessions are told apart by the client's X-Session-Id header. Without on or off it shows the scope and the sessions kept. Changes apply to the next request. on warns about models with a context under 100k tokens. See learn.md.

Option Description
--model <id or alias>... Only these models. all, or leaving it out, means every model
--print <session id> Show the note of a session
--json JSON output
goethe api learn on
goethe api learn on --model my-model
goethe api learn off --model my-model
goethe api learn --print my-session-id

goethe api gateway

Where the API listens, and how many client addresses are allowed.

Option Description
--bind <address> Listen on 127.0.0.1 (this machine only), 0.0.0.0 (all addresses), one IP of this machine, or an interface such as wg0, whose address is followed
--json JSON output

goethe api domain

The DNS record that serves the API under your own domain name, with this machine's address filled in.

Option Description
--check <domain> Check that the name points at the API and that it answers there

goethe serve --public

Opens the API on a public address for a limited time, for API keys you choose, so you can give someone outside your network a URL and a key. The normal API address, local or VPN, stays as it is.

goethe serve --public 5h --key my-app      # open for 5 hours for the key my-app
goethe serve --public 1d                   # open again, with the keys and port of the last opening
goethe serve --public                      # status: URL, time left, keys
goethe serve --public shutdown             # close now

Opening prints the URL, each key with the models it may use, the certificate to send along, and a curl command to try it. The keys stay the same every time you open the gateway, so a recipient can keep using the key you sent. Running it again while it is open keeps the gateway open and starts the timer over: goethe serve --public 5h means 5 hours from now, not 5 hours added to the time left. Connections in progress are not interrupted. The keys, port and address limits given that time replace the old ones. goethe status shows the window while it is open, and a node linked to the platform shows the public URL and when it closes on its page, within a few seconds of opening or closing.

Option Description
--public <duration> How long to stay open: minutes, hours or days, such as 30m, 5h or 1d, at most 7d. shutdown closes it; nothing shows the status
--key <name or id> API keys that may use the public address; repeatable or comma-separated. Remembered for the next opening
--allow <cidr> Only these client addresses or ranges may connect, such as 203.0.113.7; repeatable. Without it anyone may connect, with a key
--port <port> The public port (default 8444, or the last one used)

The recipient verifies the gateway with the certificate goethe prints, GOETHE_HOME/nginx/certs/public.crt. It holds no secret: curl --cacert public.crt https://<address>:8444/v1/models -H "Authorization: Bearer <key>". Most OpenAI-compatible clients take it through SSL_CERT_FILE or their CA-bundle setting. If nobody can connect, forward the port to this machine on your router or allow it in your cloud firewall; goethe does not open ports on routers. The public listener uses IPv4.

Security precautions

  • Closed by default: nothing listens on the public port unless a window is open. Shutdown or the end of the window removes the listener.
  • Time limit checked twice: goethed closes the listener when the time runs out (it checks every 2 seconds, and on start it never reopens an expired window). In addition, every request on the public address checks the end time, so a request after it is refused even if closing failed or goethed was stopped.
  • Only chosen keys: only the keys named with --key work on the public address. Every other key gets 403 there. Removing a key from the list, or shutdown, applies to the next request.
  • No admin keys: admin keys are refused when opening and on every request. Expired keys are refused when opening, and a key that expires during the window stops working when it expires. goethe warns about a key that may use every model; a key limited with --models is safer to share.
  • Model scope unchanged: a key reaches only the models it is limited to, as on the normal address.
  • Separate listener: public requests reach goethe on their own internal address, so they can never be mistaken for requests from your own network, and no header can change that.
  • API routes only: health, readiness, admin and metrics endpoints are not served publicly.
  • HTTPS only: TLS 1.2 or 1.3, with its own certificate for the public listener. Plain HTTP connections are dropped.
  • Stricter limits than the normal address: 10 requests per second per client address (bursts of 20) and 16 connections per address, plus the same body size limit and header and body timeouts.
  • Optional address limit: --allow admits only the given clients; all others get 403.
  • Checks before opening: nothing changes unless every check passes: the gateway and goethed are running, the keys are valid, and the port is free and is not the normal gateway's port. If nginx does not accept the new listener, the previous state is restored.

GPUs and system

goethe gpu

GPUs with their memory use, whether Goethe may use them, the process ids on each (Goethe's in green, others in red) and a bar of memory bandwidth use. The bar turns blue past the line at 70 %. On a terminal the table updates every half second until you press q; piped or with --json it prints once. The JSON adds processes (pid, goethe) and memory_util_percent.

Option Description
--deny <gpuN>... Keep new models off these GPUs; models already on them stay
--allow <gpuN>... Allow these GPUs again
--json JSON output

goethe hw

Command Description
goethe hw profile GPUs, CPU, memory, disk, OS, container and cloud provider. GPU links, NUMA nodes and processes are in --json and hardware_state.json; goethe gpu shows the processes
goethe hw pick-gpus [--model <id>] [--tp <N>] Where goethe load would place a model right now, and the memory it needs

goethe doctor

Checks the machine and the setup: GPU and driver, compiler, Python environment, gateway, ports and keys. Each problem comes with its fix.

Option Description
--json JSON output
--probe-public Also test that the public address answers

goethe update

Installs the latest Goethe. Loaded models keep serving.

Option Description
--check Only show what's available
--engine Also update the inference engine
--yes Don't ask
--allow-downgrade Install the published version even if it's older

goethe uninstall

Removes Goethe and the models it installed. Folders of your own that you registered stay. A node linked to the platform is logged out first (best effort) and its credentials go with the rest.

Option Description
--keep-models Keep the installed models
--yes Don't ask

goethe completion [install | remove]

Tab completion for bash, zsh and fish. Commands, subcommands and flags complete, and so do live values: installed models (by full id, by the name after the organisation, in any case, and by alias), GPU names, API key ids and names, network interfaces and bind addresses. The shell asks goethe for them at each Tab, so they are always current.

Command Description
goethe completion Whether it is on for each shell
goethe completion install Turn it on for your shell (--shell bash|zsh|fish for another)
goethe completion remove Turn it off again

fish and bash with the bash-completion package load the script from their own completion folders; for zsh, and bash without bash-completion, install adds a short marked block to ~/.zshrc or ~/.bashrc, and remove takes only that block out. The installer turns it on for your shell (GOETHE_NO_COMPLETION=1 skips that), and goethe uninstall removes it.

goethe --version

Prints the version, and the upgrade command when a newer version is available. goethe --build-info adds the commit and build date.

Platform

Linking is optional. A node that is not linked never contacts the platform. A linked node's goethed sends a health snapshot every 10 seconds, and right after a model loads or unloads: hostname, OS, environment (bare metal, VM, container, cloud), network addresses, the gateway address (and the public gateway's address and end time while goethe serve --public is open), GPUs with memory use, installed and loaded models, and the node's API keys (name, key, model scope, expiry; the platform stores keys encrypted and shows them only to members who may manage the node). It never sends engine keys, prompts, traces, file paths, environment variables or command lines. Inference never depends on the platform.

goethe login

Links this node to a workspace. Prints a link and a code, then waits until the login is approved in the browser (Ctrl-C cancels; the code expires after 15 minutes). Logging in again replaces the current link and logs the old node out. A running goethed sends its first heartbeat within a second; otherwise it starts with goethe up.

Option Description
--authkey <msh_ak_...> Link without a browser, with an auth key from the platform; --authkey - reads it from stdin so it stays out of the process list
--platform-url <url> Another platform (default: GOETHE_PLATFORM_URL, else https://platform.meshapplied.com). Must be HTTPS; plain HTTP only for localhost and *.localhost

The installer takes the same flags: curl -fsSL .../install.sh | bash -s -- --authkey msh_ak_... (or GOETHE_AUTHKEY=...).

The credentials and the heartbeat state live in GOETHE_HOME/platform/ (directory 0700, files 0600). Goethe refuses a credentials file or folder other users can read, a symlink, or one you do not own, and says how to fix it; it also refuses a GOETHE_HOME that every user can write to (a group-writable one is fine). When the platform revokes the node (for example after it is removed there), heartbeats stop and goethe status says Revoked until the next goethe login.

goethe logout

Removes this node from its workspace and deletes the local credentials. When the platform cannot be reached, the local link is still removed and the node shows offline on the platform until you remove it there.