Every goethe command and its options. For a walkthrough, see the user guide.
goethe <command> [options]
goethe <command> --help
- 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). - Every action is a word, and flags only change how it runs:
goethe gpu allow gpu0 gpu1,goethe api keys create my-app,goethe models alias set fast org/model. - Commands are grouped: what concerns the API is under
goethe api(keys, expose, allow, domain, share), and model housekeeping undergoethe models(recommend, scan, alias). Learning and traces have their own commands,goethe learnandgoethe trace. - GPUs are named as
goethe gpulists 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 formzai-org__GLM-5.3-Flashworks too. A mistyped id gets a suggestion. - Commands that list things accept
--jsonfor 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 |
- Start and stop:
goethe,up,status,down - Models:
install,models,models recommend,models scan,models alias,remove - Running models:
load,unload,run,ps,logs - API access:
api,api keys,api expose,api allow,api domain,api share - Learning and traces:
learn,trace - GPUs and system:
gpu,doctor,update,uninstall,completion,--version - Platform:
login,logout
On a terminal, plain goethe opens the menu on its own screen:
| Entry | What it does |
|---|---|
| Quick setup | Install a model, serve it through the API and choose who can reach it, step by step |
| Install models | A table of the catalog models that fit this machine's GPUs, with their size and the VRAM they need, under the machine's VRAM and storage. Space selects models, a custom Hugging Face id and a token for gated models can be typed below the table, and Enter installs them |
| API keys and gateway | API keys (create, scope, show or delete), network exposure (local, VPN or private network, public) and the public address (goethe api share) |
| Status | Whether Goethe runs, the environment, then live tables of the GPUs (VRAM, processes, allowed or denied, memory bandwidth), CPU and memory |
↑↓ move, Enter opens, ← goes back, q quits. On the main menu 1, 2 and 3 pick a color theme (default, sea, earth); the choice is remembered. Without a terminal, goethe prints the commands.
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 |
Whether Goethe is running, the API address, the names and ids of your API keys, the models it serves, and the public gateway while it is open (goethe api share). 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>).
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 |
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 |
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-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 |
--gpu <gpuN>... |
Default GPUs; several split the model across them |
--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 |
Don't ask: download without confirming, and with --load load next to other programs on the GPU |
--force |
Download again, or replace an existing install, and rebuild the model's saved settings from the defaults |
--fallback |
Serve the model with its plain runtime (llama.cpp or SGLang) when its kernel pack cannot run here, even with GOETHE_ALLOW_FALLBACK=0 (the plain runtime takes over by default) |
--name <id> |
Id for a local folder |
--copy |
Copy a local folder instead of linking to it |
-- <options> |
Extra engine options, after --, saved with the model |
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 |
|---|---|
<folder> |
Only this folder (default: all of them) |
--yes |
Add every supported model without asking |
--json |
JSON output |
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 |
Short model names for clients. Changing what an alias points to moves every client that uses it.
| Command | Description |
|---|---|
goethe models alias |
List the aliases |
goethe models alias set <alias> <model> |
Point an alias at an installed model; clients send the alias as the model |
goethe models alias remove <alias>... |
Remove aliases |
To change the settings a model loads with, use goethe load with --save.
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 unless --traces delete |
--force |
When unloading first, don't wait for requests in progress |
--traces keep|delete |
What happens to the model's traces, without asking |
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; the number given is the split |
--tp <N> |
Split the model across N GPUs that Goethe picks (not with --gpu) |
--ep <N> |
Expert-parallel size, for mixture-of-experts models |
--ctx <N> |
Context length |
--max-conc <N> |
Requests served at the same time |
--save |
Keep --gpu, --ctx, --max-conc and the options after -- as the model's defaults; a bare -- clears the saved options |
--dry-run |
Show where the model would be placed now and the memory it needs, and load nothing; with --save it only stores the defaults |
--replica |
Start another copy, to serve more traffic |
--yes |
Don't ask: load on busy GPUs, or next to other programs on the GPU |
--fallback |
Serve the model with its plain runtime when its kernel pack fails to open, even with GOETHE_ALLOW_FALLBACK=0 |
--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 load zai-org/GLM-5.3-Flash --ctx 32768 --save --dry-run # only store the defaults
goethe load zai-org/GLM-5.3-Flash --dry-run # where would it go?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 |
Tries a model by hand. With text it prints one reply (a text model), an embedding summary (dims= norm= [first 4]) or, for an audio file, its transcript. With no INPUT on a terminal it opens an ephemeral chat screen; with no terminal, or --plain, a plain > prompt (a speech model records from the microphone). An installed model that is not loaded is loaded first, like goethe load, and unloaded when run ends unless --keep; run never installs. It talks to the model's own engine on 127.0.0.1 with its engine key, not through the gateway, and creates no API key.
| Option | Description |
|---|---|
--keep |
Leave a model loaded that run loaded |
--plain |
No chat screen |
--thinking |
Show the model's reasoning, dimmed, with the answer (hidden by default) |
Chat screen: the model on the top line, the conversation from the top row down (it follows the reply as it streams), your line and the keys at the bottom. Typing: Enter sends, Esc opens the command keys. Commands: m pick or load another model (starts a new conversation), e export, r record (speech models), i or Enter back to typing, q quit (Enter confirms, q goes back; Ctrl-C asks the same). Up and Down or k and j scroll a line, Page Up and Page Down (or Ctrl-U and Ctrl-D, also while typing) a page, g and G jump to the top and the end; the screen follows the stream again at the end or on the next send. /audio PATH sends an audio file to a speech model; an embedding model shows dims= and norm= for each line. Nothing is written when you close it. e writes goethe-chat-<UTC time>/ here in the trace format (0700 folder, 0600 files; embeddings as embeddings.json), with the model's raw text, reasoning included.
Running models with the runtime serving each (goethe-engine runs a kernel pack; llama.cpp and sglang are the plain runtimes), their GPUs, port, memory, restarts, requests in progress and speed. goethe models --json gives installed models the same runtime.
| Option | Description |
|---|---|
--json |
JSON output |
| Option | Description |
|---|---|
<target> |
A model (id, alias or words from its name), an instance id, goethed for Goethe's own log, or gateway for the API gateway's log |
-f, --follow |
Keep printing new lines |
-n, --lines <N> |
Number of lines (default 100) |
Goethe rotates its logs every hour.
The API address, how to authenticate, your API keys and a curl command to try it. The models it serves are in goethe status.
| Option | Description |
|---|---|
--json |
JSON output (api, goethed_running, keys, models) |
Lists API keys with their limits and today's usage, or creates or revokes one. On a terminal, goethe api keys alone opens a full-screen key manager (see below).
| Command | Description |
|---|---|
goethe api keys |
List the keys (--json for scripts) |
goethe api keys create <name> |
Create a key |
goethe api keys revoke <key id>... |
Revoke keys, by the id goethe api keys shows |
| Option | Description |
|---|---|
--expires <when> |
With create: expiry, days from now such as 30d, or a date such as 2027-01-31 |
--rpm <N> |
With create: requests per minute (default 120, 0: unlimited) |
--models <a,b> |
With create: only these models |
--admin |
With create: admin key, for health endpoints and every model |
--raw |
With create: print only the key, for scripts |
--json |
List as JSON |
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 keys revoke <key-id>The key manager is 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. Scripts use the commands above, since the menu needs a terminal (at least 64×12).
Who can reach the API. Without an argument it shows where the API listens and how many client addresses are allowed.
| Command | Description |
|---|---|
goethe api expose |
Show where the API listens and who may connect (--json for scripts) |
goethe api expose local |
This machine only |
goethe api expose vpn |
A VPN or other private network (recommended) |
goethe api expose public |
A public address (needs --allow <their-ip>/32 and --yes, or y on a terminal) |
goethe api expose <address or interface> |
Listen on 127.0.0.1, one IP of this machine, or an interface such as wg0 (followed). Not 0.0.0.0: use expose public |
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.
expose public never binds every interface on a leftover allowlist. Name the clients with --allow, confirm with --yes (or y), and only then does it listen on 0.0.0.0. Opening every client address needs the hidden --dangerously-allow-all-inbound --yes.
| Option | Description |
|---|---|
--interface <name> |
With vpn: the network interface to serve, such as wg0; needed without a terminal when there are several |
--allow <cidr> |
With vpn or public: a client address or range to allow; required for public; repeatable |
--yes |
Apply without questions. Public still needs --allow (or --dangerously-allow-all-inbound) |
--json |
With no argument: the status as JSON |
goethe api expose local
goethe api expose vpn --interface wg0
goethe api expose public --allow 203.0.113.7/32 --yesLists the client addresses allowed to reach the API, or adds or removes one.
| Command | Description |
|---|---|
goethe api allow |
List the allowed addresses |
goethe api allow add <cidr>... |
Allow addresses or ranges, such as 203.0.113.7 or 192.168.1.0/24 |
goethe api allow remove <cidr>... |
Remove addresses or ranges |
| Option | Description |
|---|---|
--note <text> |
With add: a note stored with the new entries |
The DNS record that serves the API under your own domain name, with this machine's address filled in.
| Command | Description |
|---|---|
goethe api domain check <domain> |
Check that the name points at the API and that it answers there |
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 api share 5h --key my-app --allow 203.0.113.7/32 # prints the URL, the key and the certificate to send
goethe api share 5h --key my-app --dangerously-allow-all-inbound # every address (rate limits still apply)
goethe api share 5h --key my-app # reopen: keeps addresses from the last share of those keys
goethe api share # status: URL, each key with its time left and addresses
goethe api share stop --key ci # stop sharing one key
goethe api share stop # close the public gateway
Every shared key uses the same public gateway, each until its own time and from its own addresses. The gateway stays open until the last key's time ends. A key whose time has ended is refused while the others keep working, and the addresses only it allowed are dropped from the gateway. Sharing a key again starts its time over (5h means 5 hours from now) and replaces its addresses; the other keys are not touched. Without --key, the keys of the last opening are shared again. 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, so a recipient can keep using the key you sent. Connections in progress are not interrupted. The menu's Public address page does the same with a form: the key, how long, and optional addresses. goethe status shows the gateway while it is open, and a node linked to the platform shows the public URL and when it closes on its page.
| Option | Description |
|---|---|
<duration> |
How long to share the keys: minutes, hours or days, such as 30m, 5h or 1d, at most 7d. stop stops sharing; nothing shows the status |
--key <name or id> |
API keys to share, each until the duration; repeatable or comma-separated. With stop, the keys to stop sharing |
--allow <cidr> |
Only these client addresses or ranges may use the keys given, such as 203.0.113.7; repeatable. Without it, addresses from the last share of those keys are kept; with none, Goethe refuses to open |
--dangerously-allow-all-inbound |
Allow every address (0.0.0.0/0). Rate limits still apply (10 requests/s per client, burst 20, 16 connections). Not with --allow |
--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, each for its own time: only shared keys work on the public address, each until its own time; every other key gets 403 there. Stopping a key, or
goethe api share stop, 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
--modelsis 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.
- Client address required: every shared key has an allowlist (
--allow, or addresses kept from the last share of those keys). Nginx admits only that union and always ends withdeny all. Every address (0.0.0.0/0) needs--dangerously-allow-all-inbound; this machine's own public IP is refused as--allow. Goethe also checks the client on every public request. - 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.
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 trace on
goethe trace on --key my-app
goethe trace offLets 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 learn on
goethe learn on --model my-model
goethe learn off --model my-model
goethe learn --print my-session-idThe GPU table of the menu's Status page: per GPU the VRAM in use, a 10-block bar (Goethe's models in the theme's main color, other processes in white, free memory dotted) and the total; the processes, one per line (another program's as a red process id, a Goethe model as its process id and model, with the engine's other processes such as └ scheduler below it); ALLOWED or DENIED; and a bar of memory bandwidth use with its percent. A legend follows the table. On a terminal it updates every 100 ms until q or ←; piped or with --json it prints once. The JSON adds processes (pid, goethe) and memory_util_percent.
| Command | Description |
|---|---|
goethe gpu deny <gpuN>... |
Keep new models off these GPUs; models already on them stay |
goethe gpu allow <gpuN>... |
Allow these GPUs again |
| Option | Description |
|---|---|
--json |
JSON output |
Checks the machine and the setup: GPU and driver, compiler, Python environment, gateway, ports and keys. Each problem comes with its fix. With --hardware it prints the hardware profile instead: 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. To see where goethe load would place a model right now, and the memory it needs, use goethe load <model> --dry-run.
| Option | Description |
|---|---|
--json |
JSON output |
--public |
Also test that the public address answers |
--hardware |
Print the hardware profile instead of the checks |
Installs the latest Goethe. Loaded models keep serving. It then checks the kernel pack of each installed model against the signed index: when the pack changed, only the blocks the installed pack lacks are downloaded, the new pack is verified and swapped in, and the previous one is kept for one rollback. A loaded model keeps its old pack until reloaded. goethe load says once a day when a newer pack exists.
| Command | Description |
|---|---|
goethe update |
Update Goethe, bundled nginx when its sha differs, already-installed engines, and kernel packs |
goethe update engine |
Update only the installed engines (the ternary runtime too, when it is installed) |
goethe update rollback |
Put the previous kernel pack of every model that has one back |
CLI help text stays the source of truth for flags and examples. A later pass can regenerate the command tables from clap while keeping the prose paragraphs above hand-written.
| Option | Description |
|---|---|
--check |
Only show what's available |
--yes |
Don't ask |
--allow-downgrade |
Install the published goethe and goethed even if older than this build (a build ahead of the release otherwise keeps its binaries); not with engine |
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 |
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 listen 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.
Prints the version, and the upgrade command when a newer version is available. goethe --build-info adds the commit and build date.
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 api share is open), GPUs with memory use, installed and loaded models, and the node's API key inventory (id, name, prefix, model scope, expiry — never the raw key). It never sends API key secrets, engine keys, prompts, traces, file paths, environment variables or command lines. Inference never depends on the platform.
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 |
--lifetime <when> |
How long the login lasts: never, or a time such as 12h, 30d or 4w. On a linked node it only changes that |
--platform-url <url> |
Another platform (default: GOETHE_PLATFORM_URL, else https://goethe.sh). 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.
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.