SPARK CHEATSHEET                                 lp ~/.spark/docs/CHEATSHEET.txt

Every command has -h.
Local model by default; configured servers receive text you send.
No telemetry. README.md says what leaves this machine.

AT THE PROMPT
  ? words   or   words?   Enter   the command lands in your line
  Enter again                     runs it. ! means read it first
  ?? words                        follow up on the last answer
  Esc s                           ask about the line you are on
  Esc s on an empty line          explain the failed command. Again: the fix
  Esc r                           describe a past command to find it again
  Esc v | Esc x                   ask by voice, stop the speaking (voice on)
  Esc k                           move spark's row up or down
  spark keys                      the keys spark added to your shell
  spark keys NAME KEY | off | on  move one (ask Esc a), or all off or on
  cmd 2>&1 | explain              what went wrong, and the fix
  spark <TAB>                     complete commands and names
  a paste of 2 or more lines      one line about it. Nothing runs

SPARK
  spark                           what answers now
  spark status                    the full report, and what needs you
  spark off | on                  turn the prompt line (? words) off or on
  spark <words>                   one answer
  spark @FILE <words>             ask about a file
  spark last                      the last answer again
  spark soul                      who spark is
  spark soul edit [--core]        change it (--core: all of it)
  spark soul reset                back to the default
  spark memory                    what spark remembers: the facts, numbered
  spark memory add <words>        remember a fact (40 at most)
  spark memory forget N|<words>   forget one
  spark memory on|off|clear       use the facts, or forget them all
  spark history                   past threads (conversations), and fixes
  spark clear --history           forget past threads (kept ones stay)
                                  and what spark check --history shows
  spark ver                       the version, the license, the repo
  spark ver --credits             what spark uses and the notice
  spark ver --sbom                what spark depends on, as CycloneDX JSON

CHAT
  spark chat [words]              talk with the model. Esc, Ctrl-D or /q ends
  spark chat --thread N [words]   an older thread (N from spark history)
  spark chat --reveal N|auto|off  how fast the reply appears
  Ctrl-C                          stop a reply
  /help                           the commands
  /resume [N] /new /clear /keep   older thread, fresh, wipe, keep longer
  /last /model                    the last turn, which model
  /copy [N]                       a reply to the clipboard
  /save [FILE]                    the chat to a file
  /read @FILE [question]          an answer that quotes the file
  /do [--sandbox] <goal>          a task, as spark do runs it
  /aloud /again /reveal           read aloud or stop, say it again, the pace

TASKS
  spark do <words>                a task, one command at a time. At each step:
                                  Enter runs, e edits, s skips, q quits,
                                  r reads it again. Danger needs yes typed
  spark do --sandbox <words>      the steps run in a copy, offline. Then the
                                  diff. yes applies it. Weaker on macOS
  spark do --sandbox --detach ... the same with nobody there
  spark do --review [ID]          the waiting runs, or one of them
  spark do --accept ID            apply a waiting run without showing it
  spark do --discard ID           drop a waiting run
  spark do --porcelain <words>    JSON lines, for a program
  spark do -- <words>             a goal that starts with -

READING AND WRITING
  the text comes on stdin: < FILE or a pipe
  spark edit <words>              rewrite the text
  spark edit ? [words]            ask about it. ? alone reviews it
  spark edit ? --source [words]   discuss someone else's text. Secrets held
  spark edit --at N               what comes next at byte N
  spark edit --watch FILE         comments on a draft each time you save
  spark ask [words]               what the text does not answer
  spark read [words]              an answer, every line quoting the text
  spark read --part N             part N of a long text
  spark read --warm               send the text ahead; the answer comes sooner
  spark drill [--name NAME]       practice questions. --name keeps a schedule
  cmd | spark watch <words>       one line when the stream matches
  cmd | spark reveal [N]          show piped text at N characters a second
  spark reveal [N|auto|off]       how fast replies appear
  --name NAME  --about WORDS      hints: the text's name and what it is
  --thread ID                     edit ? and ask: keep the exchange
  --ledger [clear] --name NAME    what was declined, asked or scheduled

MCP TOOLS (the servers on the list, ~/.config/spark/mcp.env)
  spark mcp [NAME]                the servers, their tools and arguments
  spark mcp add NAME PATH [WORDS] put a server on the list
  spark mcp rm NAME               take a server off the list
  spark mcp trust NAME [on|off]   believe what its tools say of themselves
  spark mcp call NAME TOOL K=V    run one tool. One that can destroy asks yes
  spark mcp read NAME [URI]       its resources. --watch shows each change
  spark steps <words> < TOOLS     the tool calls for the words, as JSON

THE MODEL
  spark model                     the models and their licences
  spark model NAME | auto | none  choose the model this machine runs
  spark model --chat [NAME|auto|none|list]  a second model for chat
  spark model budget [N]          the share of memory models may use
  spark model add URL             your own (--license, --sha256)
  spark model rm NAME             delete a downloaded model
  spark model verify              check the downloaded models

THE SERVER AND OTHER MACHINES
  spark serve                     what answers, the models, the page
  spark serve on | off [--force]  start or stop the engine and the page
  spark serve boot [on|off]       start spark at every boot: always on, headless
  spark serve share [on|off]      one model for every user here (Linux)
  spark serve --login             the page's address and login, QR for a phone
  spark serve --login --new       a new admin token. Old logins end
  spark serve --audit [N]         what the admin did
  spark serve https               the page's certificate, who must trust it
  spark serve https CERT KEY      serve the page with your pair (--name HOST)
  spark serve https own | off     a pair of this machine's; or plain http again
  spark user [list]               the users here
  spark user add NAME             add a user. The token shows once
  spark user remove NAME          delete a user and their data (asks)
  spark user login [NAME] | logout
  spark user token --new          a new token. Other logins end
  spark user claim                move older chats into your account
  spark client [URL|off]          another machine's model; off: your own again
  spark client URL --key-file F   use your own llama-server, its key in F
  spark client URL --pin FP       trust that page's certificate (or --ca FILE)
  Traffic between machines is plain HTTP unless the page has a certificate.
  The admin token can run any command on the machine.

THE PAGE (open the address spark serve --login prints)
  1..5                            chat, activity, do, settings, help
  /   Enter   Shift+Enter         the input, send, a new line
  n   j / k                       new chat, next / previous chat
  r   ?   Esc                     refresh, the help page, stop

THE MACHINE
  spark setup [--yes]             name, user, model and voice
  spark setup --engine URL        set up with your own llama-server
  spark check                     is spark ok: every check, what to fix
  spark check --all | NAME...     every row, or those rows. exit 0 = no failure
  spark check --history [NAME]    what changed and when, newest first
  spark check --fresh | --watch N ask again now, or every N seconds
  spark check --report            a block to paste into a bug report
  spark check --porcelain         every row, tab separated
  spark update [--dry-run]        the newest signed release
  spark uninstall [--dry-run]     remove spark from this machine (asks first)
  spark uninstall --purge         your soul, memory and users too
  spark stats [--week|--all]      how fast the model answers, waits, cache hits
  spark stats --sends             what left this machine, over the network
  spark bench [--spark|--chat]    measure the model's speed
  spark bench --line [N]          time N prompt-line questions
  spark bench tune [show|apply]   find the fastest settings, then use them
  spark bar [line]                the status in one line, for a bar
  ~/.config/spark/site.env        name, user, model, the other machine
  ~/.config/spark/spark.env       ports, engine, history, memory
  config values                  environment, spark.env, site.env, default
                                 first non-empty value per key in each file

VOICE AND LOOK
  spark voice                     the voice settings
  spark voice clear [--anyway]    read aloud in a clear voice
  spark voice on                  this machine's own voice
  spark voice off [--remove]      no voice (--remove frees the space)
  spark voice rate N              the speed, 50 to 300
  spark voice test                say one line
  spark voice listen | stop       ask by voice, stop speaking
  first use                       586 MB on Linux, 602 MB on macOS
  spark awaken                    give this machine a personality and a look
  spark look [on|off|auto]        motion, colour and the face
  the face                        waits, answers, rests above your prompt
  spark height [N]                the row spark writes in, 1 to 5

LINUX
  systemctl --user status spark-serve spark-forge
  journalctl --user -u spark-serve -n 50
  Void: sv status ~/.config/spark/sv/*
  Fedora, openSUSE: open the page's port for other machines
    sudo firewall-cmd --permanent --add-port=8081/tcp
    sudo firewall-cmd --reload

MACOS
  launchctl print gui/$UID/spark.serve
  launchctl kickstart -k gui/$UID/spark.serve     restart it
  Alt is Option: Option-s

WINDOWS
  wsl --install -d Ubuntu-24.04   then install as on Linux

DOCUMENTS
  docs/INSTALL.md                 install, models, other machines, updates
  docs/CHEATSHEET.txt             this page
  docs/CHANGELOG.md               what each release changed
  docs/ROADMAP.md                 what comes next
  docs/CONTRIBUTING.md            how to send a change
  docs/REFERENCE.md               the maintainer's reference