JoyPro2 Discord GitHub
Engine (CLI)

engine llm

Show:

10 commands of engine llm. Each with every option and every value it takes, what it does, which GUI buttons use it, and an example.

#engine llm

written
engine llm status|recommend [--ram-gb N] [--vram-gb N] [--gpu <name>] [--gpu-vendor nvidia|amd|intel] [--cores N] [--avx2 true|false]
For beginners

Shows the state of the optional local AI model: switched on or off, ready or not, the chosen model, the downloaded runtime, this PC's hardware and which model size JoyPro recommends for it. engine llm recommend prints only the recommendation. Settings > Local AI shows this status (Refresh reads it again), and every AI action checks it first.

engine llm status --text
Advanced
  • Without options the hardware is detected (RAM, graphics cards with video memory, cores, AVX2).
  • --ram-gb, --vram-gb, --gpu <name>, --gpu-vendor nvidia|amd|intel, --cores, --avx2 true|false replace the detected values, to see what JoyPro would recommend for another PC.
  • The recommendation: about 8 GB video memory: the large model on the graphics card; about 4 GB: the medium one; else on the processor by memory and AVX2 (medium, small, tiny), or none below about 4 GB of memory.
  • Which commands can use the model: engine relations from-text, engine relations assistant, engine relations chat, engine relations duplicates --instruction, engine arrange ask and engine relations plan (Manage with AI). Auto Group, Auto Assign, the Setup wizard, the suggestions and the cockpit database never use it.
  • Read-only; no profile is needed.
Technical internals
  • Output: JSON (Enabled, Ready, SelectedModel, Hardware, Recommendation, the runtime, your own llama.cpp, the models with size, licence, installed, recommended), or --text. recommend: the recommendation alone.
  • Exit code 1 with Invalid --ram-gb value: ... (and the same for the other values) or an unknown argument.
  • Files: %LOCALAPPDATA%\JoyPro2\Llm\settings.json, the model list DB\Llm\models.json.
  • Related: engine llm download, engine llm use-local, engine llm enable, engine llm start, engine llm server.

What it does The hardware, the model JoyPro recommends for it (size, quantization, GPU or CPU), downloaded models and runtime; the options replace detected values (what-if).

OptionValuesMeaning
--ram-gbswitch (no value)
--vram-gbswitch (no value)
--gpu<name>
--gpu-vendornvidia amd intel
--coresswitch (no value)
--avx2true false
Every value as a command line
engine llm --gpu-vendor nvidia
engine llm --gpu-vendor amd
engine llm --gpu-vendor intel
engine llm --avx2 true
engine llm --avx2 false

Used by the GUI Settings: Turn on the local AI · Settings: Set up the local AI · Relations: Make a plan · Relations: Preview · Relations: Send · Settings: Start now · Settings: Refresh · Settings: Download and switch on · Settings: Remove model · Settings: Use these files · Settings: Stop using them · Settings: Set up

Example

engine llm status|recommend --text

#engine llm download

written
engine llm download [<model> | --model <model>] --accept-license [--runtime auto|cpu|vulkan|cuda] [--no-runtime]
For beginners

Downloads a local AI model and the llama.cpp runtime it runs in, checks both, and switches the model on. Nothing downloads without --accept-license. Settings > Local AI > Download and switch on (after ticking I accept the size and the licenses above) runs it.

engine llm download --accept-license --text
Advanced
  • <model> (or --model <id>): a model id of DB\Llm\models.json; without it, the chosen or recommended model.
  • --accept-license: without it the command only names the download (size, source, licence) and fails.
  • --runtime auto|cpu|vulkan|cuda: the llama.cpp build (auto: Vulkan with a graphics card, else CPU); an explicit choice is remembered. --no-runtime downloads the model only.
  • The model comes from its pinned source and is checked by SHA-256; a model already downloaded and verified is not fetched again. A stopped download keeps its part and the next download resumes it.
  • After success the model is chosen and the local AI is switched on. No profile is touched.
Technical internals
  • Files: %LOCALAPPDATA%\JoyPro2\Llm\models\<file> with <file>.sha256, the runtime in Llm\runtime, the progress in Llm\download-progress.json (the GUI follows it), Llm\settings.json.
  • Output: JSON (Model, Runtime, Consent, Messages, Path), or --text.
  • Exit code 1 with Downloading needs your consent. ... Run again with --accept-license., Unknown model '...', Unknown runtime '...', Download failed: ... or the cancel message.
  • engine llm cancel stops a running download. Related: engine llm remove, engine llm.

What it does Downloads a model (positional or --model; default: the chosen model, else the recommended one) and llama.cpp's server, checks their SHA-256 and switches the model on; without --accept-license only the size and licenses are shown.

OptionValuesMeaning
--model<model>The model id to download (same as the positional <model>); default: the chosen model, else the recommended one.
--accept-licenseswitch (no value)
--runtimeauto cpu vulkan cuda
--no-runtimeswitch (no value)
Every value as a command line
engine llm download --runtime auto
engine llm download --runtime cpu
engine llm download --runtime vulkan
engine llm download --runtime cuda

Used by the GUI Settings: Download and switch on

Example

engine llm download [<model> --text

#engine llm remove

written
engine llm remove [<model>] [--all]

--all also removes the runtime and switches the model off

For beginners

Deletes a downloaded local AI model from this PC to free the space. Settings > Local AI > Remove model runs it for the chosen model.

engine llm remove qwen2.5-1.5b-instruct-q4_k_m --text
Advanced
  • <model>: that model; without a model id every downloaded model of the list is removed.
  • The model file, a partial download and its checksum file go. A removed model that was chosen is no longer chosen.
  • --all also deletes the llama.cpp runtime and switches the local AI off.
  • Your own llama.cpp and GGUF files (engine llm use-local) are never deleted.
Technical internals
  • Output: JSON or --text with Removed <model>., Removed the llama.cpp runtime. or Nothing to remove.
  • Exit code 1 with Unknown model '...'. or more than one model id.
  • Files: %LOCALAPPDATA%\JoyPro2\Llm\models, Llm\runtime, Llm\settings.json.

What it does --all also removes the runtime and switches the model off.

OptionValuesMeaning
--allswitch (no value)Apply operation to all matches (or select all relations/devices where supported).

Used by the GUI Settings: Remove model

Example

engine llm remove --text

#engine llm enable

written
engine llm enable [<model>|local] | engine llm disable

Enable switches the local model on, with a model also chooses it; disable switches it off and keeps the chosen model; for for relations from-text, the assistant, relations chat, relations duplicates --instruction, arrange ask and relations plan; local = your own llama.cpp / GGUF from llm use-local

For beginners

Switches the optional local AI model on, optionally choosing which downloaded model to use; engine llm disable switches it off. Settings > Local AI > Use the local AI model runs it.

engine llm enable qwen2.5-1.5b-instruct-q4_k_m --text
Advanced
Technical internals
  • Output: the settings as JSON, or --text (Local AI model enabled (<model>). / ... disabled ...).
  • Exit code 1 with No own llama.cpp / GGUF set (engine llm use-local --server <llama-server.exe> --model <file.gguf>)., Unknown model '...'. Models: ... or llm disable takes no model: ....
  • File: %LOCALAPPDATA%\JoyPro2\Llm\settings.json. Related: engine llm download, engine llm start.

What it does Switches the local AI model on (optionally choosing a downloaded model, or local = your own llama.cpp and GGUF) or off (llm disable, which takes no model and keeps the chosen one). It is used by relations from-text, the assistant, relations chat, relations duplicates --instruction, arrange ask and relations plan.

Example

engine llm enable --text

#engine llm cancel

written
engine llm cancel

Stops a running download; the next download resumes it

For beginners

Stops a running model download. The part already downloaded is kept, and the next engine llm download resumes it.

engine llm cancel --text
Advanced
  • It leaves a stop request that the running download checks for while it reads data; the download then ends with its cancel message.
  • Without a running download it does nothing harmful: the next download clears the request before it starts.
  • The GUI's stop button of a download leaves the same kind of request on its own.
Technical internals
  • Output: {"Cancel":true}, or --text (Download cancel requested.); exit code 0.
  • File: %LOCALAPPDATA%\JoyPro2\Llm\download.cancel.
  • Related: engine llm download, engine llm.

What it does Stops a running download; the next download resumes it.

Example

engine llm cancel --text

#engine llm find-local

written
engine llm find-local [--root <folder>]...
For beginners

Looks for a llama.cpp server (llama-server.exe) and GGUF model files that are already on this PC, and names the pair that suits the hardware. It only reads. Settings > Local AI > Find on this PC runs it and fills in the paths.

engine llm find-local --text
Advanced
  • Searched by default: llama-server.exe on the PATH, folders like llama.cpp, AI, LLM, models and tools on the fixed drives, your Downloads, the Hugging Face cache, LM Studio's model folders and JoyPro's own model folder. --root <folder> (repeatable) searches only these folders.
  • At most 7 folder levels deep and about 25 seconds; Ollama's own server and blobs are skipped.
  • Only language models count (no vision projectors, vocab-only or embedding files, from 50 MB; of a split model the first part).
  • Recommended: the largest model that fits completely in the graphics card's memory, else the smallest that fits the memory; a GPU build of the server when there is a graphics card.
  • Changes nothing; use engine llm use-local to take the pair.
Technical internals
  • Output: JSON (Searched, Servers with backend, Models with size, FitsGpu, FitsRam, BestServer, BestModel, Reason, Seconds), or --text.
  • Exit code 0; 1 for an unknown argument.

What it does Looks for a llama-server.exe and GGUF models already on this PC (read-only) and names the pair that suits the hardware.

OptionValuesMeaning
--root<folder>

Used by the GUI Settings: Find on this PC

Example

engine llm find-local --text

#engine llm use-local

written
engine llm use-local [--server <llama-server.exe>] [--model <file.gguf>] [--gpu-layers auto|all|N] [--context N] [--template server|chatml] | --clear
For beginners

Makes JoyPro use a llama.cpp server and GGUF model you already have instead of a download, and switches the local AI on. Nothing is downloaded. Settings > Local AI > Use these files runs it with the two paths; Stop using them runs --clear.

engine llm use-local --server "C:\Users\Pilot\llama.cpp\llama-server.exe" --model "C:\Users\Pilot\models\Qwen3-8B-Q4_K_M.gguf" --text
Advanced
  • --server: llama-server.exe (or its folder); --model: the .gguf file. A missing one is taken from the search of engine llm find-local.
  • --gpu-layers auto|all|<n> (auto: llama.cpp decides), --context <n> (512 or more), --template server|chatml (server: the GGUF's own chat template).
  • --clear forgets the two paths; when they were in use the local AI is switched off. Your files stay where they are.
Technical internals
  • Output: JSON or --text (Model: local, the runtime path and the message Using your llama.cpp (...) with ...; the local AI model is on. Nothing was downloaded.).
  • Exit code 1 with llama-server.exe not found: ..., GGUF model not found: ..., No llama-server.exe found (searched ...), Invalid --gpu-layers value: ..., Invalid --context value: ... (512 or more). or Invalid --template value: ....
  • File: %LOCALAPPDATA%\JoyPro2\Llm\settings.json. Related: engine llm enable (local), engine llm.

What it does Uses your own llama.cpp server and GGUF model instead of a download (without paths: what find-local recommends) and switches the model on; --clear forgets them.

OptionValuesMeaning
--server<llama-server.exe>
--model<file.gguf>
--gpu-layersauto all N
--contextswitch (no value)
--templateserver chatml
--clearswitch (no value)
Every value as a command line
engine llm use-local --gpu-layers auto
engine llm use-local --gpu-layers all
engine llm use-local --gpu-layers N
engine llm use-local --template server
engine llm use-local --template chatml

Used by the GUI Settings: Use these files · Settings: Stop using them

Example

engine llm use-local --text

#engine llm start

written
engine llm start

Loads the chosen model now; started from JoyPro it stays loaded until the idle stop

For beginners

Loads the chosen local AI model now, so the next AI request answers without the loading wait. Settings > Local AI > Start now runs it. Started from JoyPro, the model stays loaded until the idle stop; from a command line it ends again when the command ends.

engine llm start --text
Advanced
  • Needs a usable model: the local AI switched on and a downloaded model (with its runtime) or your own llama.cpp and GGUF.
  • The model runs in its own llama-server process on this PC. engine llm server shows it, engine llm stop ends it and frees its memory.
  • No profile is touched.
Technical internals
  • Output: JSON (Started, Model, ModelId, Pid, LoadMs, StaysLoaded), or --text (Started the local AI model <name> (process <pid>, <s> s); ...).
  • Exit code 1 with The local AI model cannot start: <reason> (for example the model is off or not downloaded) or The local AI model (<name>) did not start: ....

What it does Loads the chosen model now; started from JoyPro it stays loaded until the idle stop.

Used by the GUI Settings: Start now

Example

engine llm start --text

#engine llm server

written
engine llm server | engine llm stop

What runs now / end it and free its memory

For beginners

Tells whether JoyPro's local AI model is loaded right now, which model and how much memory it uses. engine llm stop ends it and frees that memory.

engine llm server --text
Advanced
  • Started from JoyPro, the model stays loaded between requests until the idle stop; from a command line every request starts and ends its own model process, so server usually says Not running. there.
  • stop ends only the process JoyPro recorded as its model server (not another program's llama.cpp) and forgets it.
  • No profile is touched.
Technical internals
  • Output of server: JSON (Running, and when running Pid, Model, LastUsedUtc, IdleMinutes, Busy, WorkingSetBytes), or --text (Running: <model> (process <pid>) / Not running.). Output of stop: JSON (Stopped, Pid), or --text (Stopped the local AI model (process <pid>). / The local AI model is not running.). Exit code 0; 1 with an extra argument.
  • File: %LOCALAPPDATA%\JoyPro2\Llm\server.json (the running server; removed by stop).
  • Related: engine llm start, engine llm.

What it does What runs now / end it and free its memory.

Example

engine llm server --text

#engine llm fake-server

written
engine llm fake-server [--port N] [--port-file <path>] [--response <file>] [--serve <folder>] [--log <file>] [--lifetime <s>]
For beginners

A test helper, not for players: a small stand-in for the llama.cpp server that JoyPro's automatic tests use, so the AI paths and the model download can be tested without a real model or the internet. It listens on this PC only and ends by itself.

engine llm fake-server --port 0 --port-file "C:\Users\Pilot\AppData\Local\Temp\fake-port.txt" --lifetime 60
Advanced
  • --port N (default 0 = a free port); --port-file <file> receives the port it got.
  • --response <file>: the answer to every completion request; answers separated by a line #next are given one per request, the last one repeated. Without it the answer is {}.
  • --serve <folder>: files of that folder are downloadable (with resume), for the downloader tests.
  • --log <file>: every request is logged. --lifetime <s> (default 300): it ends after that many seconds at the latest.
  • Only the loopback address; nothing of the profile or settings is touched.
Technical internals
  • Answers GET /health, POST /completion, POST /v1/chat/completions and GET /files/<name>.
  • Exit code 0 when the lifetime is over; 1 with Invalid --port value: ..., Invalid --lifetime value: ... or an unknown argument.
  • The engine starts it itself instead of llama.cpp when the variable JOYPRO_LLM_FAKE_RESPONSE names a response file.

What it does A test stub that answers like llama-server and serves files with HTTP Range (no model involved).

OptionValuesMeaning
--portswitch (no value)
--port-file<path>
--response<file>
--serve<folder>
--log<file>
--lifetime<s>

Example

engine llm fake-server --text