The soil commands (reference)
save, list, load, info · every command and every variant, with the @ = where,
The commands available once Soil Cloud is connected. In conversation, describe what you want in plain language and the model picks the right tool.
Two sigils, one rule each: `@` = where, `#` = which
@ says where a handover lives · the name of a shared
project. # says which one · a name you chose
(#auth-flow) or a numeric load code (#001). They are order-insensitive:
soil save @acme #auth-flow and soil save #auth-flow @acme mean the same
thing. No @ at all means personal · your own private handover.
A save (or an import) counts only when
you get back a numeric #NNN load code · that card is the proof. If there's no
#NNN, it didn't save, no matter what the chat says.
Save
| Command | What it does |
|---|---|
soil save | A personal save, auto-named from the work and given a fresh #NNN. The whole pipeline runs in one call · extract → verify → drift check, stored as a safe projection. Saves a Strong handover in one go, or returns "Needs work · missing: …" with the exact gaps. |
soil save #my-name | A personal save under your own name. The handover still gets a #NNN you can load by · the name is just a friendlier address. |
soil save @project | Saves this thread into a shared project you belong to (members only), auto-named. This is how a project accumulates over time. |
soil save #my-name @project | Saves this thread into the project under your own name. @ and # work in either order. |
Every save · personal or project · also records working-style observations: the saving model answers a few situational working-style questions, the answers are stored raw with the handover (never scored, never blocking the save), and they render as a clearly labeled block when the handover is loaded.
Names are kept, never overwritten
Every named save is preserved. Saving #my-name when that name already
exists doesn't replace the old one · Soil keeps both and stores the new save
as #my-name-001 (then -002, …), each a distinct, uniquely loadable
handover. There is no "re-save over the same name." So if you just want a
clean snapshot of where things stand right now, save · nothing you saved
before is touched.
Load
| Command | What it does |
|---|---|
soil load #001 | Loads one exact handover by its numeric code, as a paste-ready restore brief. An unknown code is reported not-found, never a substitute. |
soil load #my-name | Loads your named handover. |
soil load @project #001 | Loads one thread inside a project, by its code. |
soil load @project #thread-name | Loads one thread inside a project, by its name. |
soil load @project | Loads the project · the project knowledge, every thread listed and attributed, the newest inline. The compounding restore (see below). |
A load also carries the save's recorded working-style observations in a clearly labeled block inside the restore prompt · personal loads included.
List + info
| Command | What it does |
|---|---|
soil list | Your handovers and your projects · everything you can load, newest-first, each with its #NNN and readiness band. |
soil list @project | All threads in one project · code, name, contributor, readiness · so you know what to load. |
soil info | Project + handover counts, recent handovers, account status (identity masked). |
Personal vs projects · the part that matters
A personal save is a standalone snapshot · complete on its own, free. It's the right tool for "save this state now, load it later or somewhere else."
A project is where your work accumulates over time. Each soil save @project adds a thread, and soil load @project brings the project back:
the project knowledge in full (the decisions, constraints, and architecture the
work has settled on), every thread listed and attributed, the newest restored
inline, and any older one readable on demand with soil load @project #NNN. The
more you save into it, the more complete the project knowledge becomes · a fresh
AI, or a teammate, can pick up the accumulated work, not just one thread. That
accumulation is the paid capability; see
projects & saving over time.
A bare `#NNN` is always personal
Without @, every command stays personal: a bare soil load #001 loads one
of your own handovers and never reaches a project thread. To reach a project,
name it with @project. Numeric-only names are refused at save time · codes
like #001 are auto-assigned, never chosen.
Under the hood, tool names use the soil_* prefix (soil_save, soil_list,
soil_load, soil_info). There is also a helper tool, soil_prepare, that
the model calls automatically at the start of a save · it is never something
you type. It returns the extraction recipe as text in every client: the
sections a handover should fill, the
working-style questions for this save, and · for an
@project save · the project-knowledge digest to disposition. Clients that
support structured tool results additionally get the same recipe as a
machine-readable payload (the section keys, the questions with their ids, the
digest, and a prepare id that attributes the following save to that exact
prepare).
For walkthroughs see save a handover and load a handover. For the connect flow see Soil Cloud.