SPARK CHEATSHEET                                          lp CHEATSHEET.txt

SPARK
  spark                           status: server, widget, soul, last answer
  spark off | on                  silence / restore the widget, every pane
  spark soul [edit|reset]         who it is: the default, or your own
  spark memory add <words>        a fact it keeps  memory forget N  drops it
  spark memory [on|off|clear]     the facts it recalls on every answer
  spark ver                       about, version, credits
  spark ver --sbom                what it depends on, as CycloneDX JSON
  spark chat [words]              a conversation (/help for its verbs)
  spark chat --thread N [words]   go on with an older thread (spark history)
  /resume [N]   /clear   /new     in the chat: an older thread, wipe, fresh
  spark <words>                   one answer, streamed     spark last  again
  spark do <words>                a task, one confirmed command at a time
  spark @FILE words               ask about a file (first 4 kB, last 12 kB)
  spark edit [?] words < FILE     rewrite / complete (--at N) / ask (?) stdin
  spark ask < FILE                three questions that text does not answer
  spark read <words> < FILE       what a source says, every line quoting it
                                  (16 kB a part; --part N reads one)
  spark drill < FILE              the source becomes questions it answers;
                                  --name keeps a widening schedule
  <stream> | spark watch <words>  silent until a line matches, then one line
                                  quoting it (tail -f, journalctl -f)
  ... | spark reveal [CPS]        the answer letter by letter at a reader's
                                  pace (default 30 a second); only at a tty
  spark edit --watch FILE         comment on a draft as you save it
  spark history [clear]           the threads kept here; clear removes them
  try:
  ? words   or   words?   Enter   the command lands in your line, hint above
  Enter again                     runs it (! = read it first; a recursive
                                  rm says how many files and bytes it clears)
  ?? words                        follow up on the last answer (same thread)
  ?? how do I change the model    spark knows itself: it names its own verbs
  [a multi-line paste]            2+ lines on an empty prompt: one verdict
                                  line; nothing runs until your own Enter;
                                  one that looks like a secret is not sent
  Esc s                           ask about the line you are on, no ?
  Esc s on an empty line          the failed command, piped to explain;
                                  again for the fix; the fix, as a fact
  command not found -> Esc s      the line that installs it
  Esc r                           describe a past command; it lands in
                                  your line (Esc r cycles); Ctrl-R stays
  cmd 2>&1 | explain              what went wrong, and the fix
  spark <TAB>                     completes the verbs; second word too

ON THE LAN (server / client)
  spark model [NAME|auto|none]    choose one; model list = the table
                                  (--porcelain: data; grounded = audition)
  spark model budget [N]          percent of RAM+GPU auto may use (10-95)
  spark model add URL             add your own (--sha256, --license required)
  spark model verify              sha256 every downloaded file now, exit 1 bad
  spark serve [on|off]            one LAN address, token required
  spark ember [NAME|auto|none]    a second model for chat; ember list = same
  spark forge [on|off]            the page and the API on the LAN; status bare
  spark forge --print-url         the page's login URL; at a tty the admin
                                  token and a QR to scan (--no-qr)
  spark forge --print-client      what another machine needs: URL + a user
  spark forge token --new         rotate the admin token
  spark forge audit [N]           every admin action, sealed (--porcelain)
  spark user [list]               the named users, each a sealed store
  spark user add NAME             mint an account; the token and its QR
                                  show once (--no-qr)
  spark user login [NAME] | logout  act as NAME here; forget the login
  spark user token --new          rotate your token; old logins die
  spark headless [on|off]         up from boot, never asleep (the machine
                                  that stays on)
  spark share [on|off]            one engine for this machine's OS users: a
                                  spark group shares it (Linux); each own soul
  spark client [URL|off]          use another machine's spark; none here
  spark brain                     which server answers now

THE PAGE (spark forge --print-url)  chat first; keys when no input has focus
  1..5                            chat, activity, do, settings, help
  r  refresh                      ?  help
  /                               focus the input (Esc blurs it)
  Enter | Shift+Enter             send | a new line
  n                               a new thread  j / k  next / prev thread
  Esc                             stop the answer; else blur; else close
  share -> add to home screen     an app on iOS; a browser shortcut on Android

THE MACHINE
  spark setup                     first run: name, user, model, light it up
  spark check                     drift report; exit 0 = every promise kept
  spark check --watch 5           redraw every 5 s     --selftest  prove rows
  spark check --chaos             rehearse the failures: break, red, remedy
  spark check --report            a paste-safe block for an issue: statuses
                                  only -- no value, no path, no name
  spark update [--dry-run]        the newest release; main on a dev clone
  spark uninstall [--purge]       remove spark: shows, asks yes; keeps yours
  ./bootstrap.sh --dry-run        what a rebuild would change (never sudo)
  ~/.config/spark/site.env        name, user, model, budget, peer, theme ...
  ~/.config/spark/spark.env       ports, engine, history, memory
  long output (help, check, lists) pages via $PAGER (less); piped stays plain

THE INTERFACE
  spark theme NAME | list | show  one palette: console, tmux, micro; none=off
  ~/.config/spark/themes/NAME.env your own palette: the same 21 THEME_* keys
  spark quiet start on|off        no banner, one-line serve/forge + bare spark
  spark quiet login|boot on|off   Linux: motd + kernel line; GRUB
  spark quiet audio on|off        no sound from spark (both OSes)
  spark font FACE SIZE | list     console font (Linux) / Terminal.app's font

LESS OFTEN USED
  spark stats [--week]            tok/s, latency, cache hits by mode, baseline
  spark stats --sends             what left, in bytes: by destination and day
  spark bench [tune]              llama-bench; tune finds the best settings
  spark bench tune show | apply   the winner; apply writes spark.env, restarts

LINUX
  systemctl --user status spark-serve spark-forge spark-check.timer
  journalctl --user -u spark-serve -n 50     (spark-forge likewise)
  ~/.local/state/spark/forge.log             one line per request (both OSes)
  arch: sudo pacman -S --needed PKG; never -Sy alone (sudo pacman -Syu first)

MACOS
  launchctl print gui/$UID/spark.serve         is the agent loaded? (.forge too)
  launchctl kickstart -k gui/$UID/spark.serve  restart it
  spark headless on: both live in system/; restart and stop need sudo launchctl
  Alt is Option: Option-s, not Cmd-s

WINDOWS (Ubuntu 24.04 on WSL 2 -- Linux to spark)
  wsl --install -d Ubuntu-24.04    then INSTALL.md section 1, the Linux way
  the CPU build; no console (the font is Windows Terminal's); no GRUB
  units: [boot] systemd=true in /etc/wsl.conf, then wsl --shutdown

BESIDE THE CORE (kept in docs/, not tied to a release)
  docs/TOUR.md                    a first hour: twelve small things to try
  docs/APPS.md                    editors and tools that speak to spark
  docs/SHELL.md                   spark's own shell for a machine that is
                                  only an AI box: spark shell, spark bar
  docs/TROUBLESHOOTING.md         a box that will not join the WiFi: one
                                  WiFi daemon per card, then the logs