Command reference
The CLI keeps the four cache commands a shell is the natural place for. Everything else is the board or an API verb, called as odu surface cache <verb> --input '{…}' --json, with rootToken a field of the input.
Commands are written with the odu shorthand.
Commands
| Command | API verb | On the board | What it does |
|---|---|---|---|
odu cache use <bucket> |
bucket_describe |
a bucket’s Set up block | Prints the substituter and key settings and the nixConfig block, the netrc lines for a private bucket, and says where they go (Use it). No account for a public bucket. |
odu cache login <origin> |
— | — (a machine’s disk) | Saves a cache token for an origin in ~/.config/odu/cache/credentials. |
odu cache push |
— | — (a build machine’s job) | Uploads only the paths the bucket is missing. |
odu cache target |
— | — (reads this checkout) | Prints the one odu substituter ./flake.nix’s nixConfig names, and nothing else, refusing no flake, none or two. -o json gives {cache, origin, bucket}. The push action uses it when cache: is left out. |
odu cache push
Uploads only the paths the bucket is missing, and the bucket keeps what it takes. It talks to the cache directly, so it runs on the machine that holds the paths.
odu cache push <bucket> <path>… [--part-size MiB] [--pin NAME] [--run ID] [--commit SHA] [--whole]
odu cache push --cache <substituter> <path>…
odu cache push <path>…
| You name | It pushes to | Cache token it sends |
|---|---|---|
<bucket> |
that bucket, on the origin you logged in to or name with --origin |
--token-file, then $ODU_CACHE_TOKEN, then the saved credential |
--cache <substituter> |
the origin and bucket that cache states in its nix-cache-info |
the same |
| nothing | the one odu substituter in ./flake.nix’s nixConfig; two is refused |
only a credential saved for that origin with odu cache login |
- With nothing named, odu probes the substituter without a token, so a private bucket must be named with
--cache. - To send your own cache token to the flake’s cache, name it:
odu cache targetprints the URL to pass to--cache.
| Flag | What it does |
|---|---|
--pin NAME |
Re-points that pin at the closure this push landed, unless a path was refused. |
--run ID, --commit SHA |
State what built the paths. The bucket keeps both on every path this push stores, and its page shows them. A push that states neither leaves what a run stated. |
--whole |
Stores the closure’s upstream-signed paths too, for a client that fetches it from this bucket alone. If the service is too old to store the whole closure, the push stops before sending anything and says so. |
--part-size MiB |
Sets the size of each part of a large upload. |
--concurrency N |
Sets how many paths upload at once. |
-o json |
Prints the result as JSON. |
Why the cache token is withheld, and the rest of the push: Push.
API verbs
A service started without $ODU_ROOT_TOKEN refuses the verbs that take a rootToken with no_root_token, and keeps serving the cache. bucket_describe and bucket_paths take no credential: a bucket’s URL, its key and its path list are what it publishes to every client that can read it.
| API verb | On the board | What it does |
|---|---|---|
bucket_create |
Cache → New bucket → Create bucket | Creates a bucket. |
bucket_list |
Cache | Lists buckets. |
bucket_describe |
a bucket’s page | Returns a bucket’s URL, key and where reads are served from. |
bucket_paths |
a bucket’s Paths tab | Lists a bucket’s paths, grouped and sorted. See The board’s Cache view. |
bucket_domain |
a bucket → Domain | Gives a bucket a domain of its own, or takes it away when domain is omitted. See A domain for a bucket. |
bucket_retention |
a bucket → Retention | Changes how long a bucket keeps what nobody wants. |
bucket_migrate |
a bucket → Move to another store → Start move | Moves a bucket’s objects to another declared store. Returns the bucket, whose migration is the progress. It serves from the old store until the copy is done. |
bucket_delete |
a bucket → Delete this bucket | Deletes a bucket, its objects first. |
token_mint |
a bucket → Tokens → Mint token (write or read) | Mints a cache token, returned once. scope is read, write or admin. |
token_list |
a bucket → Tokens | Lists cache tokens with scope, expiry and last use. |
token_revoke |
a bucket → Tokens → revoke | Revokes one cache token. |
pin_create |
a bucket → Pins → Pin closure | Pins a closure against garbage collection. A name that exists is re-pointed. |
pin_list |
a bucket → Pins | Lists what each pin holds, and who made it. |
pin_delete |
a bucket → Pins → unpin | Lets a pin go. |
gc_plan |
a bucket → Dry run, and the retention field beside it | Says what the next collection would take, without taking it. |
gc_run |
a bucket → Run GC | Evicts paths past retention that nothing refers to and no pin holds: the daily collection, now. |
stats_read |
a bucket’s facts line | Shows storage and read counts. |
Every verb is typed after cache, as in odu surface cache bucket_create. Over MCP, each is named with a cache_ prefix, as in cache_bucket_create.
bucket_create
Creates a bucket, and returns its substituter URL, public key and store.
| Field | Board control | What it sets |
|---|---|---|
name |
name | the bucket’s name, in its URL |
public |
— (the board creates public buckets) | whether it is read without a cache token |
retentionDays |
— (set it afterwards under Retention) | how long it keeps what nobody wants. 90 when absent. |
upstreamKeys |
Skip upstream paths | the keys whose paths it skips, cache.nixos.org-1 by default. [] takes everything, which costs disk, for clients that cannot reach cache.nixos.org. The switch off sends []. A push with --whole stores them anyway. |
store |
where its objects live | the declared store for its objects. local by default. See Keep a bucket on S3. |
Behind a proxy, the URL is under the address you published the service at, $ODU_PUBLIC_ORIGIN, which the NixOS module derives for you.
bucket_delete
Deletes a bucket: its objects out of its store first, then the bucket, its paths, its pins and the cache tokens scoped to exactly its name. It returns the objects removed and their bytes.
- It is refused while a domain is bound to the bucket, or a move is in flight.
- There is no
odu cache delete.
Delete a bucket has the details.
gc_plan
Says what the next collection would take, without taking it. It writes nothing.
retentionDaysplans at a retention of your own. Absent is each bucket’s own, and0asks what nothing refers to and no pin holds.gc_runhas no such field, so a dry run cannot become a collection.- It takes a
rootTokenlike the other administrative verbs, but is marked read-only. An agent may ask what a collection would evict without confirming, and must not run one without.
The board’s Cache view
The board’s Cache view lists the buckets: name, public or private, how many paths, how much space, the last push, and how many reads. Click one to open its page.
| Part of a bucket’s page | What it shows or does |
|---|---|
| the facts line | the bucket’s numbers and where reads come from: reads served from cache.example.com or reads served by odu. A push updates it without a reload, and reads are added at most once a second. |
| Paths | the paths it serves: name · hash · size · pushed · reads · commit · run · wanted · kept by. See below. |
| Pins | the pins holding closures: name, system, paths, when, and who made it. Click a name for its roots, ten until you click show all. |
| Set up | the substituter URL, the public key, and tabs for nix.conf, NixOS, flake.nix, odu CLI, push and GitHub Actions |
| Root token | without server mode, asks for the root token once per visit |
| Tokens, Retention, Domain | mint and revoke cache tokens, set retention, set a domain |
| Move to another store | shown only when the service declares another store |
| Garbage collection | Run GC, and Dry run with its own retention field |
| Danger zone → Delete this bucket | deletes it, once you type its name |
Anyone may read a bucket’s page, which uses bucket_describe and bucket_paths. The administrative parts are shown to an admin, and the service checks the role again on its own.
The paths table
- It is grouped by name by default:
odu-base-0.1.0with six builds is one line with the count, total size, newest push and summed reads. The service counts over the whole bucket, not the lines on screen. - Click group by name for one line per path.
- Click name, size, pushed or reads to sort by it, and again to reverse. Show 20 more continues in the same order. Inside an open package, show N more pages its versions.
- The filter box narrows what the bucket returns.
- A hash shows its first eight characters. Its tooltip is the whole store path, and clicking it copies the path.
- kept by says why a path is still here and when it goes: see Why a path is still here.
- The path and pin lists are read when you open them. refresh paths and refresh pins read them again.
The Dry run is taken only when you click it, and again after each collection. The retention field beside it changes neither what the bucket keeps nor what Run GC evicts.
Verbs renamed since odu 1.5
A script written against odu 1.5 needs this table. The CLI’s own cache create, list, token, pin, gc and stats commands became these API verbs, so odu surface cache_create … is now odu surface cache bucket_create …. odu cache push, login and use are unchanged.
| was | now | takes rootToken |
|---|---|---|
cache_create |
cache_bucket_create |
yes |
cache_list |
cache_bucket_list |
yes |
cache_describe |
cache_bucket_describe |
no |
| — | cache_bucket_paths |
no |
| — | cache_bucket_retention (4.0) |
yes |
| — | cache_bucket_migrate (4.1) |
yes |
| — | cache_bucket_delete (4.3) |
yes |
cache_tokenMint |
cache_token_mint |
yes |
cache_tokenList |
cache_token_list |
yes |
cache_tokenRevoke |
cache_token_revoke |
yes |
cache_pin |
cache_pin_create |
yes |
| — | cache_pin_list (4.0) |
yes |
| — | cache_pin_delete (4.0) |
yes |
cache_gc |
cache_gc_run |
yes |
| — | cache_gc_plan (4.0, the dry run; retentionDays 4.4) |
yes* |
cache_stats |
cache_stats_read |
yes |
* cache_gc_plan takes a rootToken, but is marked read-only: see gc_plan.