Documentation
¶
Overview ¶
args.go is one rule, applied to every command in this CLI: a word the command has no use for is an error, not something to drop on the floor.
Go's flag package stops at the first word that is not a flag and leaves the rest in fs.Args(), and until this existed most commands here simply never looked at what was left. `grain pause -set "the queue is wedged, back in an hour"` is what that cost: -set is a boolean and the reason belongs to -reason, so the sentence the operator typed was discarded, the pause went into the store as "paused by hand", and neither the UI's banner nor the next reader of `grain pause` had any idea why this deployment had stopped. The natural spelling of the command was the one that lost the message (found by hand, task 209). `grain list junk`, `grain config junk` and `grain get 1 extra` were the same silence, more cheaply.
So each command below says how many positional words it reads, and refuses whatever is past that. The two kinds of leftovers are the same question: rest is fs.Args() for a command that calls Parse itself, and parseArgs' own return for one whose flags may come after its arguments.
The commands that take an unbounded tail on purpose say nothing here, because every word after the id is theirs: `grain comment <id> <body...>` is the one, and misplacedFlag in main.go is what that command does instead of counting.
backup.go implements the operator-facing and scheduled halves of backups. Both call pkg/backup.Service, so a backup made by hand is byte-for-byte the same shape as one made by the daemon.
cicmd.go is "grain ci": grain's own CI (pkg/ci, served as /api/ci/runs) read and driven from a terminal -- start a run against a repo and a branch, list what has run, open one run's jobs and steps, and cancel one that is still going.
ci.go beside this file is the other half of the same feature and is deliberately not this: that is the daemon's own adapter, where the engine meets the machines a job runs on. This is a task verb like `grain metrics` or `grain pause` -- it holds no store and no engine, asks a running daemon over REST (pkg/ui's HTTPClient), and takes -server and -json from main.go's own global flags. So `grain ci list -json | jq` is how a run gets into anything else, and `grain -server https://... ci show <id>` is how a run on another deployment is read.
Until this existed the API from grain/task-185 had no reader at all: watching a run meant curling the daemon and paging JSON. The two things a person actually wants out of one are what the shape here is built around -- which jobs failed, and what the step that failed printed. Hence: jobs failures-first (ci.SortJobRuns, so the pane and this agree on the order), and a step's output shown for the steps that failed, all of them under -output all, none of them under -output none.
A run's output is already bounded where it is produced (ci. MaxStepOutput truncates one step's output in the middle past 256KB with a line saying so), so nothing here re-truncates it: a terminal has a scrollback and a pipe has a `less`, and a CLI that quietly dropped the tail of a failing test's output would be hiding the one thing it was opened for.
The third thing a person wants is a run that has not finished yet, and that is `grain ci show -follow` / `grain ci watch <id>`: the same poll `grain ci run -watch` does, printing what each poll holds that the last did not (followCIRun and pkg/ci/cli's Follower), rather than one snapshot the reader has to keep asking for.
`grain ci wait`, `retrigger` and `test-history` are the sandbox CLI's verbs of the same names from outside a sandbox (external-cli #XC-26): a run named by id, pull request or branch rather than "this task's", answered in the same shapes the in-sandbox commands read and print.
The rendering of runs, listings and the cache is cicmd_print.go, and the polling and following behind -watch and -follow is pkg/ci/cli.
cicmd_print.go is how `grain ci` (cicmd.go) prints what the daemon answered: a run's jobs and steps, a listing of runs, the job cache and a run's artifacts, as text or, under -json, as the route's own body.
connections.go implements `grain connections import <file>`: the one way to give a deployment its git and model connections without the UI, for a headless or scripted install (scripts/setup.sh and `grain init` both seed through it).
The file is an import format only. Grain never reads it at runtime: this command records what it says as the deployment's connections, in the store, the same records Settings edits, and the file can be deleted afterwards. That is what replaced the secrets/github/credentials.json ladder, which grain did read on every git request (docs/single-tenant-reset.md, stage 2).
Like `grain secrets`, it works on a data dir on this host rather than through a running daemon. A daemon already running on that data dir picks the connections up on its next settings refresh.
controller.go is "grain controller ...": one-shot setup verbs an operator runs by hand against their own machine, never against a running daemon -- unlike every task-management verb in main.go, these need no store connection at all. bootstrap-github-app is the first and, for now, only one: see pkg/capability/githubsandbox's own doc comment for why a GitHub App -- not the "username and password" bwsalmon/agents#354 first asked for -- is what that capability's two secrets hold, and why this command exists to make registering one a single click rather than the account's actual password ever reaching grain.
daemon.go implements `grain daemon`, formerly its own cmd/graind binary before bwsalmon/agents#313 combined every mode into one: it runs pkg/orchestrator's RunCycle in the background on a timer, until SIGINT/SIGTERM, against one real embedded SQLite store, and -- unless -ui-addr is emptied out -- also serves pkg/ui's JSON API and static frontend directly over that same store (bwsalmon/agents#363). That used to be a separate "ui" subcommand (formerly its own cmd/ui binary), opening the store a second time -- SQLite's own file locking is what makes a daemon and a UI both writing that same file at once safe (pkg/model/sqlite's own doc comment). Folding UI serving into the same process this dispatch loop already runs in removes the need for a second process entirely: there is one process, one store connection, one thing to run behind Tailscale or IAP (the issue's own "so the server ui/api does not need auth on its own"), and cmd/grain's own task CLI is a REST client of the API this serves (main.go's own doc comment) rather than a second direct store writer.
bwsalmon/agents#254 asked for exactly this, with one simplification: by default, sandboxing is still local -- the MCP server's sandbox tools confined to a directory on this host, no isolation -- rather than a fleet this deployment shape has nowhere to run. -granule-sandboxes is the opt in to the real alternative (bwsalmon/agents#274): orchestrator.GranuleSandboxes, one real bwsalmon/granule-managed VM per run, reached over SSH. -max-workers/-max-mergers cap how many runs are in flight at once either way, and a sandbox is built for each of them and destroyed with it; nothing above pkg/orchestrator.Deps needs to change to serve more than one.
graind originally drove pkg/orchestrate, a package built independently of, and in parallel with, pkg/orchestrator (bwsalmon/agents#249) -- bwsalmon/agents#263 reconciled the two, keeping pkg/orchestrator (issue intake, directive parsing, and PR-health sync were all already wired to dispatch.Cycle there) and porting pkg/orchestrate's own capability resolution/materialization and reconcile-loop shape onto it. See README.md for what that merge kept and dropped.
Most of this file's own flags (-max-workers, -max-mergers, -poll-interval, -agent-framework, -gemini-model, -gemini-effort, -claude-model, -codex-model, -max-agent-turns, -github-host, -github-insecure-http, -gcp-project, -gcp-agent-service-account, -target-repos) are store-backed now (bwsalmon/agents#320): loadConfig writes them into model.Store's grain_config row the first time a deployment's store has none, and reads them back out of it on every start after that, so a UI or a CLI editing model.Config is what changes them from then on. Almost all of them change what this process is doing without waiting for a restart at all: liveConfig re-reads that row once per reconcile tick and hands each change to whatever it configures -- see its own doc comment for the full list, and for the settings (-github-host, -github-insecure-http, and the sandbox backend) that genuinely cannot be swapped under a live deployment and so are reported to the UI as needing a restart. What stays flags-only either has to be known before there is a store to read it from (-data-dir) or names secret material rather than being configuration itself (-gemini-api-key-file, -granule-ssh-key, -claude-oauth-token-file, -openai-api-key-file, -codex-auth-file) -- bwsalmon/agents#320's own "but not the secrets." -claude-path and -codex-path join them not because they are secret but because, like -granule-ssh-key, they name something about *this host's* filesystem rather than the deployment's own behaviour.
daemon_restarts.go answers, from inside the daemon, the question nothing on this deployment could answer on 2026-09-18: how many times has this service started lately?
It had started 52 times in eight minutes (grain/task-233). Every one of those starts failed on a flag the unit passed and the image did not define, so the deployment dispatched nothing for as long as it lasted, and nothing raised it anywhere: the UI was down with the daemon, the journal was the only record, and the journal was being filled with the crash's own output at ~200 lines a restart. It was found two hours later by a person reading it by hand.
The reading is taken once, at startup, and served from memory afterwards (ui.DaemonHealth.Starts). Twice deliberate:
- It is a question about the recent *past*, and the only process able to answer it is one that is currently running -- which, during a loop, is a new one every few seconds. Each of those processes takes the reading afresh, so whenever there is a UI up to look at, the figure on it was taken by the process serving it.
- The pane polls every few seconds and journalctl is a subprocess over a window that, in a crash loop, holds thousands of lines. Per-request would make the pane cost most where the deployment can least afford it.
Two deployment shapes ask the question differently, and both are here (grain/task-367). A host running grain-daemon.service counts starts in the unit's journal; a pod running one replica of a Deployment has no journal at all and counts the kubelet's own restarts of its container instead. The numbers are not interchangeable -- see daemonShape and newPodDaemonHealth -- so each reading travels with the words for what it is a count of and for what an operator does about it on this shape.
daemon_unknown_flags.go is how `grain daemon` reads a command line written by a *different build of itself* -- which, on every deployment scripts/setup.sh installs, is the only kind of command line it ever gets.
The unit and the image move independently. setup.sh writes grain-daemon.service once, at install time, with this build's flags baked into its ExecStart; from then on an upgrade only rewrites the image ref file the unit interpolates (pkg/upgrade/image.go), so the flags stay frozen at whatever the installer wrote while the binary behind them moves on with every upgrade and every rollback. A flag removed from the daemon therefore meets a unit that still passes it, and a flag added to the unit by a newer setup.sh meets an image rolled back past it.
Before grain/task-233 that meeting was fatal. flag.ExitOnError met "flag provided but not defined: -root-shell-control-dir", dumped the whole ~200-line usage text and exited 2; systemd restarted the service five seconds later and it did it again. That is what took this deployment down for eight minutes and 52 restarts on 2026-09-18, removed -root-shell-control-dir from the image (grain/task-193) having been the entire change -- and it buried the journal under ~10,000 lines of flag help while it was at it, so the one place an operator would look for the reason was the place the reason had scrolled out of.
So an unknown flag is read here as what it is: a configuration error, in a configuration this process cannot edit, about a setting it does not have. It is named once, loudly, with the fix beside it, and the daemon comes up. A deployment that is up with one ignored setting can be looked at, logged into and repaired; one that is in a restart loop can do nothing at all, and neither can anything it was supposed to be running.
What is *not* tolerated is a bad value for a flag this build does define (-max-workers=banana): that is this build's own setting, said wrongly, and there is nothing to fall back on. It still exits -- but with one line rather than the usage dump, for the same journal reason.
declcmd.go is "grain declarations check": a repository's own `.grain` declarations (docs/declarations.md) read out of a working tree, before any of it is pushed, and either printed or refused.
declarations.go beside this file is the other half of the same feature and is deliberately not this: that is the daemon's own source, where a repository is cloned with the credential this deployment holds and the rows are written to the store. This is a local verb -- it holds no store, asks no daemon, and takes no -server -- because the question it answers is asked from inside a checkout, usually by a CI job that has nothing but the tree.
Until this existed the only way to find out whether a declaration file was well-formed was to merge it and read `repo_declaration_sync. last_error` off the repository's settings a poll later. That is the loop the wrong way round: a file that does not parse should fail the pull request that introduces it, and `.grain/workflows` can now say so in a step of its own --
- run: grain declarations check
-- because this exits non-zero on any error and prints every verdict rather than the first (pkg/repodecl.Load joins them, for exactly this reason).
Two things here are not in the tree and have to come from somewhere else, both because of what they decide:
- The repository. Every declared id is derived from it (model.RepoDeclaredID) and it is the target of every task a declaration files, which is why no file gets a say in it -- so -repo, or the checkout's own `origin` remote, which is the same answer without the typing.
- The zone a time of day is read against. That is the schedule's explicit timezone (or UTC by default); -zone says which one to preview against when no explicit timezone is declared.
The firing preview is the other half of the point. "every: {hours: 6}" and `daily: {at: "09:00"}` are both easy to write and hard to picture, and a cadence is the one thing in these files whose mistake costs agent time rather than a parse error: -next says how many firings to work out, from now, through the same model.Recurrence.Next the reconciler fires by.
demo.go implements `grain demo`, formerly `grain ui -demo` before bwsalmon/agents#363 folded the real UI into `grain daemon` and left nothing standalone for the CLI's own store flag (-data-dir) to attach to. This mode never needed that anyway -- its whole point, unchanged, is a throwaway store nothing else is connected to (pkg/demo's seedDemo doc comment) -- so it is its own small subcommand now rather than a flag on a mode that no longer exists: a real pkg/ui.Server, over a real embedded SQLite database in a fresh temp directory, seeded with fake tasks, for trying out the frontend with no daemon, no orchestrator, no sandbox, no Gemini key and no real git repo behind any of it.
The demo itself -- the store, the seeding and every opt-in scenario -- is pkg/demo; this file is only the command's flags.
errors.go is how the task CLI ends: which exit code an error is (design/spec/external-cli/external-cli.spec.md, #XC-13), and what it writes on stderr -- a sentence by default, and under -json a single {"error": {...}} object a script can read without parsing English.
The exit code is the part a script branches on, so it says what kind of thing went wrong rather than that something did:
0 success 1 the thing asked about failed (a red CI run), or the daemon did (5xx) 2 the command was wrong: usage, a flag, an argument, a 400/404/409/422 3 the daemon would not take this CLI's credential (401, 403, sign-in) 4 no daemon answered at all (refused, reset, DNS, TLS, timeout) 5 a blocking wait ran out of time before what it waited for happened
grain export creates a standalone, verified archive bundle of a Grain deployment containing the SQLite database (checkpointing WAL) or database configuration, the controller state repository (state-repo), and all credentials and secrets.
An optional symmetric passphrase or key encrypts the bundle with AES-256-GCM.
failures.go is "grain failures": what runs said when they failed for a reason grain could not name -- neither the account's usage limit nor the provider having no capacity (pkg/agent/refusal.go, served as GET /api/unmatched-failures).
It is not a list of failed tasks, and it is not for finding out why one task failed; a task's own attempts say that, and `grain get` prints them. This answers a question about grain rather than about the work: can it still recognise a provider refusing us? Both refusal detectors match phrases somebody else's product writes, so the day one is reworded, refusals arrive here instead -- read as ordinary failures, counted against the tasks that suffered them, and contradicted by no test. Reading a week of this is how that gets noticed. A run of the same unfamiliar sentence, or a "looks like a refusal" count that has climbed, is the signal; the fix is a marker in pkg/agent.
A task verb like every other one in main.go: it asks a running daemon over REST and takes -server and -json from the same global flags.
grain import extracts a verified migration bundle into a target data directory, restores the database, state repository, team state repositories, and secrets with proper permissions, applies any needed schema migrations, and verifies credential ladder and state repo consistency.
init.go is `grain init`: taking a bare Linux host to a running deployment in one command, so that bringing one up is a command rather than a session of shell archaeology. It wraps pkg/hostinit.Init the same way setup.go wraps pkg/gcpsetup.EnsureInfrastructure -- see that package's own doc comment for what each step does and why, and why a step this process lacks the privilege for is reported with the exact command rather than aborting the run.
Unlike `grain setup gcp`, this runs directly against the host it is invoked on: there is no credential to authenticate with, only the access the invoking account already has (root or not). -dry-run prints the plan -- every read-only check Init performs, with every step that would otherwise act replaced by a description of what it would have done -- without changing anything.
init_workstation.go is `grain init workstation`: standing up a single-tenant Grain for one person or team on a workstation, laptop or VM, as that person's own account, with no root and no checkout of grain. `grain init` proper (init.go) is the operator's install of a shared deployment onto a host it takes over; this is the other end of that range.
It writes four things into the data directory and one beside the user's other systemd units, and nothing else:
- grain_policy.yml, the starter local policy (docs/local-policy.md), fail-closed: only the repositories named, no capability but grain CI's own unless one is named, the network chosen. An existing policy is kept, so a re-run never undoes the owner's own edits (-force rewrites it).
- daemon.sh, the daemon's command line, with the PATH this ran under so the daemon finds the same docker, granule and model CLI.
- secrets/github/workstation.token, when -github-token-file names a token, narrowed to the policy's repositories.
- ~/.config/systemd/user/grain.service, which runs daemon.sh.
Interactive by default: every choice not given as a flag is asked, with the detected answer as its default. -non-interactive takes the defaults instead, which is how CI and scripts run it.
Package cli is grain's command, the one binary this repo builds (bwsalmon/agents#313). cmd/grain is a one-line main over Main, and google/cmd/grain is the same main with the Google-internal registrations linked in (google/README.md).
Given no recognized subcommand, or one of the task-management verbs below, grain is a standalone CLI over pkg/ui's HTTPClient -- a plain REST client of the same JSON API (`grain daemon`'s own embedded `pkg/ui.Server`) the browser frontend speaks, driven straight from a terminal instead. It lets the caller do what a human does to a task: create one, edit its fields, attach or detach a capability, accept (approve) a proposal or withdraw that approval again, defer one for later or pick it back up, comment, and close (grain's own stand-in for "delete" -- see Client.Close's own doc comment for why) or reopen one.
This used to open the task store directly -- embedded, or a Dolt SQL server via -store-addr -- and call pkg/ui.Client's methods in-process, which made the CLI a second direct writer against whatever daemon a deployment also runs (README.md used to carry a whole "Single writer" section about exactly that). bwsalmon/agents#363 closed that gap: the daemon is the only thing that ever opens the store now, and serves pkg/ui's JSON API and static frontend itself (daemon.go's own doc comment); this talks to that API over plain HTTP, wherever an operator's network puts it -- a loopback port, an SSH tunnel, Tailscale, IAP. -server names it; there is no GitHub credential and no store flag here at all any more.
Other subcommands -- daemon, mcpserver, secrets, backup, controller, setup, sync -- select entirely different modes, each what used to be its own binary, its own flag or store carve-out, or a later addition with no business touching the task store at all. daemon (daemon.go, formerly cmd/graind) runs pkg/orchestrator's RunCycle on a timer and, unless -ui-addr is emptied out, serves the UI/API in-process too -- the standalone "ui" subcommand this project used to have is gone, folded into daemon by #363 rather than kept as a second way to open the same store. mcpserver (mcpserver.go, formerly cmd/mcpserver) speaks MCP over stdin/stdout against the sandbox tools; a running daemon forks mcpserver instances of itself -- this same binary, re-invoked with "mcpserver" as argv[1] -- rather than needing a second binary on disk (see pkg/agent/claude's own doc comment for the one place that matters today). secrets (bwsalmon/agents#357, secrets.go) sets/deletes/lists a colocated server's secrets directly on disk, no store or RPC involved. controller (controller.go) runs one-time interactive setup verbs (currently just bootstrap-github-app) against an operator's own machine, never a running daemon. setup and sync (bwsalmon/agents#358, setup.go and sync.go) bootstrap and reconcile a deployment's external GCP infrastructure and, for sync, its stored settings too -- sync reaches those over the same REST API this CLI does now, rather than opening the store itself. "demo" (demo.go) is a smaller mode still: a throwaway UI server over fake data, for trying out the frontend with no daemon, no store and no deployment behind it at all.
The task CLI itself takes no GitHub credentials at all. A task used to be a GitHub issue, so this command needed a token and a task repo to file one; a task is a store row now, and creating one is a write to the store (README, "Input is a model update, not a GitHub issue").
Folder management (docs/data-model.md's Folder tree, the containment structure a capability's `offers` are attached to) is deliberately absent: README.md already states folders are unbuilt, so there is no store-backed concept yet for a command here to manage. What a repo *does* have stored -- its own default capability set, and whether the deployment's allowlist names it -- is `grain repo` (repo.go, grain/ task-36), which is deployment configuration in the same sense `grain settings` and `grain secrets` are, not the containment tree. -repo on `create`/`update` still only ever sets one task's own target.
Schedules, templates, suites and qualification plans remain UI-only, and repo.go's own doc comment has why that is not the same question: they are authored content rather than deployment configuration, and docs/schedules.md records their absence here as an open gap waiting on somebody who needs it. The one thing here that touches any of the three is "declarations" (declcmd.go), and it writes nothing at all: it reads the templates, suites and schedules a repository declares in its own tree (docs/declarations.md) and says whether they parse, which is a question asked from inside a checkout with no deployment to ask.
This file is the dispatch and the helpers every verb shares. The task verbs are taskcmd.go (printed by taskprint.go), and `grain config` / `grain settings` are settingscmd.go (printed by settingsprint.go). size_test.go keeps every file here under a size limit, so logic that is more than flags and printing goes in pkg/.
mcpserver.go implements `grain mcpserver`, formerly its own cmd/mcpserver binary before bwsalmon/agents#313 combined every mode into one: it serves the sandbox tools and the escape hatches (ask_question, request_secret, comment_on_issue, propose_task, add_review_comment -- recorded here, relayed by orchestrator.ProcessResult once the run finishes) over its own stdin/stdout, so anything that can spawn a subprocess and speak MCP -- not just an in-process client -- can drive it. Real MCP clients (an actual `claude` or `gemini` CLI's --mcp-config, for instance) can point at this same grain binary, "mcpserver" and its own flags as the configured args, as pkg/agent/claude does.
Its sandbox tools run against one of two backends: a local directory (-sandbox-root, unchanged since before bwsalmon/agents#256 -- what pkg/mcp's own tests and tests/e2e/ still use, since neither wants a real VM), or a real granule-managed VM (-granule-vm, see package granule and pkg/mcp's NewSSHSandboxTools) -- the wiring bwsalmon/agents#256 asked for, so a run_command/read_file/edit_file/write_file call actually lands inside one of the sandbox VMs granule is running instead of the local-directory stand-in pkg/mcp/sandbox_tools.go's own doc comment describes. -granule-backend selects which of granule's two ways of running that VM -granule-vm was created with -- "docker" (the default, bwsalmon/agents#353) needs just a local docker daemon; "static-pod" needs a standalone kubelet (deploy/static-kubelet/README.md) and is resolved via crictl instead.
-pr-repo/-pr-branch add pkg/mcp's pull_request_status and the legacy GitHub-backed wait_for_checks to that roster. A run holding grain-ci gets that wait tool replaced below by the task-scoped Grain CI form, which explicitly starts and polls Grain CI without reading GitHub checks. The pull-request tools also add base_branch_status with them, which reads the same CI for the branch that work merges into (-pr-base, or the repo's default branch), so a run staring at a red check can tell breakage it caused from breakage it inherited instead of guessing. Those reads happen *here*, in this process, which runs on the controller: the GitHub credential comes off the controller's own -data-dir (the same secrets/github ladder `grain daemon` loads) and never crosses into the sandbox, so docs/design.md's split surface -- "Sandboxes: git transport only" -- is untouched. See pkg/mcp/pullrequest_tools.go's own doc comment.
-server and -task add three further tools. open_pull_request: a run that has pushed its branch can have grain open its pull request there and then, and read back what the repo's own CI makes of it, rather than exiting blind and leaving the pull request to the finish path. And recreate_sandbox: a run whose sandbox has become unusable -- a wedged guest, a full disk, a filesystem an interrupted install left in a state no command can untangle -- can have grain destroy it and build a clean one, and carry on in the turns it has left instead of failing every remaining call in a sandbox it cannot repair from inside. And update_status: a run can put one short phrase on its own task's row -- "waiting for CI", "running the test suite" -- so a person watching a task that has read 'running' for half an hour can see what that half hour is going on, rather than reading the transcript afterwards. It is the only one of the three that changes nothing: grain shows the phrase and never reads it back.
-interactive adds a fourth to that pair, for a task somebody is actually sitting with: chat, which posts a message into the task's own conversation, parks the task on it, and blocks until a person replies -- a whole turn of a conversation inside one tool call, rather than one dispatch per thing said. The waiting is done here, by polling the same daemon (daemonChat), which is what pkg/capability/selfrepair's Confirm had always needed and never had: a route to the conversation from a process holding no store handle.
-interactive with -grant naming grain#host-exec (or the retired self-repair) adds run_host_command over that route: every command it is asked to run is posted into the task's chat first, and runs only once a person there replies approve (daemonHostExecConfirm). A run that is not -interactive is not given it, since nobody would answer.
-propose-repo names a repository this deployment works in, once per repository, and adds no tool at all: it narrows one that is always registered. propose_task lets a run file a proposal against any repository this deployment works in, and nothing in the sandbox says which those are -- so a run that does not know a repository is nameable files the work against its own instead, and nobody finds out until a human retargets the proposal by hand (grain/task-144). The flag carries the daemon's own answer (model.Store.WorkRepos) into that argument's description, which is where a run reads it. Unset -- a caller with no store to ask, which is every test here -- leaves the description naming the rule without the list, as it has always read.
-grant names a capability grant this run's task holds, once per grant, and is how a grant whose whole effect is which tools a run gets reaches a run at all. Until it existed those tools were assembled by orchestrator.Config.GrantTools and consumed by nobody: every framework that remains forks a CLI and ignores agent.RunConfig.Tools, so a capability granted tools no running agent could call.
-grant https://grain.dev/capabilities/grain#source={} (once the source half of self-debug) names grain's own checkout, -grain-src-dir, which the run reads as grain-src/ and src://.
-grant api:self-debug (the REST half of self-debug, which the retired bare name still reads as) turns on list_grain_tasks, read_grain_task, read_grain_task_prompt and read_grain_task_transcript, reading grain's *other* tasks over -server, plus read_grain_metrics, reading what this deployment measures about itself over that same connection (the report `grain metrics` prints, which a sandbox holding no deployment address and no token cannot ask for any other way). The task readers were briefly retired, on the grounds that the state repository held every one of those rows as a file, and came back with the export that stopped holding them: staterepo.ExportConfig writes the settings tables and the memory ones and no others, so tasks, runs, comments and observations exist only in the daemon's database and these four tools are the only way a sandbox reaches them. A run dispatched without -server gets the tools anyway and each one refuses with a sentence saying why (mcp.NewTaskTools).
-grant grain-log adds read_grain_log, a bounded read of this host's own systemd journal (pkg/capability/grainlog). It is served from here for the same reason the pull-request tools are: this process runs on the controller, so journalctl is a subprocess away, and -- far more importantly -- so is the redaction. -grain-secrets-dir names the directory whose credentials are cut out of every line before it is returned. Nothing in that directory is ever served to a run; the flag exists so that this process can recognize those values in the journal and remove them, which is the entire basis on which a sandbox is allowed to see any of it. Without the flag the tool is still on the roster and refuses every call, rather than answering with a journal it could not clean.
Both api:self-debug and grain#journal are read-only, which is why both can be served from here with no further hop. pkg/capability/selfrepair's run_host_command is served too, but only beside chat (see -interactive above), because its one tool blocks on a human's reply in the task's own chat.
-run-deadline is the moment grain will cancel the run this process serves. It adds no tool: it makes every tool result carry how much wall-clock time is left, once there is little enough of it to change what a run should be doing (pkg/mcp's run_deadline.go). The prompt states the same budget up front, and is read once, hours earlier -- this is the half that reaches a run at turn 200.
The flags name the daemon to ask and the task to ask about. Unlike pull_request_status above, both of these are *writes*, and writes stay grain's: this process asks the daemon over its REST API rather than acting with a credential -- or, for the sandbox, an authority -- of its own. See daemonPullRequests and daemonSandbox below.
mergequeue.go is `grain merge-queue`: the merge queue from a terminal -- the pull requests queued to merge, the batches and CI runs testing them, and the gates holding any of it back -- read from the same deploy://merge-queue a sandbox's `grain merge-queue` reads, over the daemon's GET /api/fs/deploy/merge-queue (design/spec/external-cli/ external-cli.spec.md, #XC-27).
The route answers ci:read as well as deployment:read, and under ci:read alone it leaves out every repository the caller may not read, so the filtering is the daemon's rather than this command's: -repo narrows what the daemon was going to show, and cannot widen it. It only reads; forcing a merge stays `grain force-merge`, behind merge:force.
metrics.go is "grain metrics": the throughput and latency report (pkg/metrics, served as GET /api/metrics) printed at a terminal -- including the daemon's own reconcile tick, which is what says whether a queue wait in that report was contention or scheduling.
It is a task verb like every other one in main.go rather than a mode of its own -- it asks a running daemon over REST, holds no store, and takes -server and -json from the same global flags -- so `grain metrics -json | jq` is how a number here gets into anything else.
It asks the same question the endpoint takes, and no smaller one: a span said either as a length ending now (-window) or as actual dates (-since/-until), and a scope (-repo, -author) narrowing which tasks the numbers are about. The CLI is how a report reaches a pull request comment or a weekly note, and "how did acme/widgets go last month" is a question asked there more often than anywhere else.
pause.go is "grain pause": the two gates that stop this deployment dispatching, read at a terminal, and the flags that change the one an operator owns.
The agent usage-limit gate (orchestrator.Pause, served as GET /api/pause) is the involuntary one -- a provider said one model connection's credential has no budget left in this window -- and -lift is DELETE /api/pause, the same thing the UI banner's "Resume now" button sends: every pause the caller may lift, or with -connection just that connection's.
The pipeline gate (model.PipelinePause, GET/POST/DELETE /api/pipeline-pause) is the deliberate one: somebody decided this deployment should pick no new work up. -set closes it and -resume opens it again. grain also takes one of these for itself around a check of an upgrade it has just installed, and such a pause names the check it is waiting for and lifts itself when that check is done -- which is why the reading below says which task a pause is waiting on rather than only that there is one.
A bare `grain pause` prints both, because "why is nothing being dispatched?" is one question and an operator should not have to know which of two mechanisms to suspect before they can ask it.
grain/task-132 wired that gate to the browser and nothing else, so an operator ssh'd into a deployment, or driving one with `grain -server`, had two ways to find out why a queue of ready tasks was dispatching nothing: the daemon's journal, or the detail of an attempt they would have to know to open. `grain metrics` deliberately does not carry it (pkg/ui/pause.go's own doc comment on why a live gauge does not belong in a report computed over rows), which leaves this.
It is spelled as a noun with a flag, like `grain settings`, rather than as a `grain resume` verb: every verb in this CLI acts on a task named by its argument (approve, retry, reopen), so a bare `grain resume` would read as one of those with its id left off. `grain pause` prints the reading; `grain pause -lift` changes it and prints what it left behind.
repoprint.go is how `grain repo` (repo.go) prints a deployment's repos and one repo's defaults, work ownership and workflows.
sandbox_budget_cmd.go is `grain sandbox-budget`: whether one sandbox of the deployment's own shape fits inside its sandbox budget, the same check grain init makes (hostinit.CheckSandboxBudget). scripts/setup.sh's readiness report runs it, which is how a host too small to admit any run is told so by setup.sh as well as by grain init.
sandboxnet.go is where the services a sandbox has to reach get published: the git proxy, the three model proxies, the package cache and the Actions cache.
All six are the same shape -- bind an ephemeral port, hand a sandbox a URL naming it -- and until this file existed each of them wrote that shape out for itself. Four copies of:
bindHost := "127.0.0.1"
if advertise != "" {
bindHost = "0.0.0.0"
}
ln, _ := net.Listen("tcp", bindHost+":0")
url := "http://" + ln.Addr().String()
if advertise != "" {
url = fmt.Sprintf("http://%s:%d", advertise, ln.Addr().(*net.TCPAddr).Port)
}
which is four chances to get it wrong, and it had already gone wrong once: three of them asked sandboxAdvertiseHost(cfg), which answers for whichever backend this deployment runs, while startModelProxy read cfg.granuleGitProxyHost directly. Nothing ever copies the container or Kubernetes flag into that field, so under -container-sandboxes or -k8s-sandboxes the model proxies bound loopback and advertised loopback while the git proxy and both caches were correctly on the address sandboxes can route to -- a deployment where an agent could clone but not reach a model.
That bug is not interesting on its own. What is interesting is that it was invisible: nothing named the set of services a sandbox must reach, so nothing could notice one of them answering a different question. Fabric is that name. A service published through it cannot disagree with the others about where sandboxes are, because it is not asked -- and Endpoints makes the set something a caller can enumerate rather than something spread across four files, which is what a second implementation (a sandbox host that is not this machine, reached over pkg/tunnel) needs in order to publish all of them without being edited every time one is added.
The package cache's *interception* half is deliberately not here. Its two listeners are on fixed ports (443 and 80) at an address a sandbox's DNS has been pointed at, so the routing key is a hostname and not a URL, and packageCacheDNSAddrs/packageCacheTransparentAddrs already derive the pair from one value for the same don't-let-them-drift reason this file exists. Publishing an address rather than a URL is a second method on Fabric when something needs it, not a thing to bend Serve into.
schemaversion.go implements `grain schema-version`: prints pkg/model.SchemaVersion, the store schema version this build was compiled against, and exits.
bwsalmon/agents#394's staging deploy script (../scripts/setup.sh) is the caller: pkg/model.SchemaVersion's own doc comment says it is bumped exactly when Tables or Views change in a way Store.Init's own `CREATE TABLE IF NOT EXISTS` cannot safely reconcile an existing database into -- Init adds a table that is missing outright, never a column on one that already exists, so a build newer than the database it finds would otherwise start silently against stale columns instead of refusing or fixing anything. Comparing this number against a marker recorded on the data disk at the previous deploy is what lets setup.sh decide whether to move the store aside before starting grain-daemon.service, without duplicating the constant itself (or its definition of "breaking") anywhere outside pkg/model.
secrets.go implements `grain secrets`, the CLI's own answer to bwsalmon/agents#357: given -data-dir naming the same root a colocated `grain daemon` was started with (daemon.go's own -data-dir, "root directory for the store, secrets, and sandbox roots"), it edits the files under <data-dir>/secrets directly -- no daemon RPC of any kind, since pkg/secrets.Store already reads fresh off disk on every Resolve. That also means it only ever works when run on the same host as the server: -data-dir is a local filesystem path, so pointing it at the daemon's own root is only possible from where that root actually lives.
It never opens the task store: a secret has nothing to do with a task, so main's dispatch routes "secrets" here the same way it already does for daemon/ui/mcpserver, ahead of runCLI's own store-connecting setup.
list prints which secrets exist and which keys each one holds, never a value -- the same "tell what's set, not what it is" restriction pkg/secrets.Store.List and pkg/ui's own secrets endpoints hold to. set is the only way a value moves through this command at all, and it deliberately never takes one as an argv flag -- anything on a command line is readable back by anyone else on this host with a `ps` -- reading it instead from -value-file or, left unset, from stdin.
secretsrepo.go is the daemon's side of pkg/secretsrepo: where the secrets repository lives under -data-dir, what authenticates its pushes, when it is synced, and how the git proxy keeps it inaccessible to every sandbox. This repository holds nothing but grain's ciphertext, so there is no version of "a task working in the secrets repository" that this deployment wants.
settingscmd.go is `grain config` and `grain settings`: reading and changing a deployment's stored settings over the daemon's API, checking a capability's or an agent's credential, and how all of that is printed.
settingsprint.go is how `grain config` and `grain settings` (settingscmd.go) print a deployment's settings and a credential check.
setup.go is `grain setup`, bwsalmon/agents#358: a mode alongside daemon/ui/mcpserver (main.go's own switch), not one of runCLI's task-store commands, because it needs no store -- it exists to bootstrap the external infrastructure a store, or anything else here, would run against on a genuinely new installation.
`grain setup gcp` wraps pkg/gcpsetup.EnsureInfrastructure: it builds the two GCP service accounts the gcp-key/gemini-key capabilities need and grants the IAM roles that let the minter account administer the agent account's keys (and, with -enable-gemini-key, mint API keys project-wide). scripts/setup.sh already does the *host* half of a new install (build, install, systemd, laying out the SQLite store's directory) but only ever seeds an already-minted GRAIN_GCP_SERVICE_ACCOUNT_KEY_FILE -- README.md's own "Accepted limits" list says plainly that "GCP token minting has never run against a real project," and this is what an operator runs first to have one to seed setup.sh with. -mint-key plus -key-out produces exactly that file.
Not everything here can always be automated: whatever GCP identity this runs as (Application Default Credentials by default -- the same `export GOOGLE_APPLICATION_CREDENTIALS=...` pattern a gcp-key capability's own sandbox placement uses) may lack permission for one step (most commonly, creating IAM bindings needs an Owner/IAM-Admin role a project Editor does not have). Rather than aborting, EnsureInfrastructure records that step as manual with the exact gcloud command to run, and cmdSetupGCP prints every manual step at the end -- safe, and expected, to run this command again afterward: every step is get-or-create, so it picks up wherever the manual steps left off.
state.go is `grain state`, the operator's own handle on the state repository (pkg/staterepo) -- the git repository holding the database this deployment runs on.
Like `grain secrets`, it edits files under -data-dir directly rather than talking to a daemon, so it only works on the host the server runs on. The config repository is always controller-local; this command inspects, validates and exports it but never connects it to a remote.
statemanager.go manages the controller-local configuration repository for the daemon and its UI. One manager owns the open repository used by native grain/config pull requests and the export loop. Its lock keeps a merged configuration import from racing an on-demand or timer export.
stateresets.go retains notices for configuration changes that reset values. The config repository is controller-local, so there is no external pull request on which the deployment can post them; returning ErrNowhereToAnnounce tells pkg/staterepo to keep the notice for the UI and journal instead.
sync.go is `grain sync`, bwsalmon/agents#358: the command a GitHub Action calls, against a live deployment, whenever a config repo's checked-in configuration changes -- the reconciliation half of "add commands to the grain cli to allow us to bootstrap external infrastructure on a new installation, and the ability to run a syncing command in a github action when code or configurations change."
It is a mode of its own (main.go's switch, next to daemon/mcpserver and setup), not one of runCLI's task-store commands, mainly so a "gcp"-only sync -- one with no "settings" section -- never needs -server, or anything else about a running daemon, at all.
`grain sync -config path.json` reads one file with up to two independent, optional sections:
- "settings" is unmarshaled straight into ui.UpdateSettingsRequest and applied through HTTPClient.UpdateSettings, against -server, the same running daemon `grain settings` itself talks to (bwsalmon/ agents#363: there is no store flag here to open the database directly with any more) -- sync's whole value over that is that the settings live as one reviewable file in a config repo instead of a workflow step's own imperative flag list, and UpdateSettingsRequest's pointer fields already give "only the keys present in the file change anything" for free, no extra work here. Under -dry-run it goes to PlanSettings instead (grain/task-241), the same request through the same validation with the write left off, and prints the same diff -- so a pull-request check can say what a file would do to the settings, which is the section with the wider blast radius of the two it can plan.
- "gcp" re-runs pkg/gcpsetup.EnsureInfrastructure, the same reconciliation `grain setup gcp` uses for a brand new installation (setup.go's own doc comment) -- run here on every sync instead of once at install time, so IAM drift (a binding removed by hand, a newly-enabled gemini-key capability that needs a grant it didn't before) gets repaired automatically. It never mints a new minter key -- gcpsetup.Options.MintMinterKey's own doc comment explains why that stays a one-time, explicit `grain setup gcp -mint-key`.
Both sections use the exact same "safe to re-run, nothing to do if nothing changed" discipline scripts/setup.sh already holds itself to, so pointing a workflow at `grain sync` on every push touching the config file is the whole of what "run this in a GitHub Action when code or configurations change" needs -- see this package's own README section (README.md) for the workflow shape and how it reaches a deployment whose UI/API is bound to loopback only.
taskcmd.go is the task verbs of the CLI main.go dispatches to -- get, create, update, approve, defer, comment, close, retry and the rest -- and how a task is printed.
taskprint.go is how the task verbs (taskcmd.go) print a task, a list of tasks and one task's detail.
`grain version`: prints the build version information stamped into the binary.
Index ¶
Constants ¶
const ( EncryptedBundleMagic = "GRAIN_MIGRATE_ENC_V1" PBKDF2Iterations = 100000 SaltLength = 16 NonceLength = 12 KeyLength = 32 ManifestFileName = "manifest.json" // ExportFormatVersion 2 added team state repositories // (state/teams/<team>.bundle, listed in ExportManifest.TeamStateRepos). // This build writes none, since grain/config is the only configuration // repository, and ignores any an older build's bundle carries; a // version 1 bundle has none and still imports. ExportFormatVersion = 2 )
const DefaultSandboxPortBase = 9728
DefaultSandboxPortBase is where that block starts unless -sandbox-port-base says otherwise.
Three constraints picked it, and a replacement has to meet all three:
- Below the ephemeral range. Linux hands out 32768-60999 by default (/proc/sys/net/ipv4/ip_local_port_range), and a block inside it collides with this daemon's own outbound connections -- rarely, and therefore at the worst possible moment.
- Aligned to SandboxPortBlockSize, so the block is maskable as well as rangeable. 9728 is 0x2600.
- Clear of what grain already uses: 4242 for the UI (80 and 8420 on older installs), 8422 for the retired executor listener, 12000-12255 for -granule-base-port's NAT forwards, and 443/80/53 for the package cache's interception and resolver -- which are fixed by their protocols and so are not in this block at all (see Fabric.Host).
Variables ¶
This section is empty.
Functions ¶
func Main ¶
func Main()
Main dispatches on argv[1] before parsing anything else: "daemon", "demo", "mcpserver", "secrets", "controller", "setup", "init" and "sync" are modes with their own, unrelated flag sets, so they are matched exactly and handed the rest of argv verbatim rather than folded into runCLI's own flag.FlagSet. Anything else -- including no arguments at all, or a leading global flag like -json -- falls through to the task CLI exactly as it always has, so a task command itself is never allowed to collide with one of the mode names above (none of the ones below do).
func RegisterCredentialSource ¶
func RegisterCredentialSource(name string, src CredentialSource)
RegisterCredentialSource makes src the credential of every context whose auth is name, replacing any source registered under it; a nil src removes it. Register from an init function, before Main.
func SignInRequired ¶
SignInRequired is the error a CredentialSource returns for a missing or expired sign-in: exit 3, saying "not signed in to <provider>: run <fix>", with fix as the -json error's fix.
Types ¶
type CredentialRequest ¶
type CredentialRequest struct {
// Context is the context's name, Server its URL, Audience its
// audience ("" for none).
Context, Server, Audience string
}
CredentialRequest is what a CredentialSource is asked for.
type CredentialSource ¶
type CredentialSource interface {
// Token is the bearer credential for req. A source whose local
// sign-in session is missing or expired returns SignInRequired, so
// the CLI stops at once and says how to renew it.
Token(ctx context.Context, req CredentialRequest) (string, error)
}
CredentialSource mints the bearer credential for a context whose auth is the name it was registered under (external-cli.spec.md#XC-10): a wrapper distribution's sign-in to the proxy its deployments sit behind, which core knows nothing about.
type CredentialSourceFunc ¶
type CredentialSourceFunc func(ctx context.Context, req CredentialRequest) (string, error)
CredentialSourceFunc is a CredentialSource from a function.
func (CredentialSourceFunc) Token ¶
func (f CredentialSourceFunc) Token(ctx context.Context, req CredentialRequest) (string, error)
Token calls f.
type ExportManifest ¶
type ExportManifest struct {
FormatVersion int `json:"formatVersion"`
CreatedAt time.Time `json:"createdAt"`
GrainVersion string `json:"grainVersion,omitempty"`
SchemaVersion int `json:"schemaVersion"`
DatabaseType string `json:"databaseType"` // "sqlite" or "postgres"
StateRepoBranch string `json:"stateRepoBranch,omitempty"`
StateRepoHead string `json:"stateRepoHead,omitempty"`
Encrypted bool `json:"encrypted"`
// TeamStateRepos are the per-team configuration repositories
// (grain/config-<team>) an older, multi-team build's bundle carried.
// This build never writes it, and import reads it only to say it is
// ignoring them.
TeamStateRepos []RetiredTeamStateRepo `json:"teamStateRepos,omitempty"`
Files []FileManifest `json:"files"`
}
type FileManifest ¶
type RetiredTeamStateRepo ¶
RetiredTeamStateRepo is the part of an older bundle's entry for a team configuration repository that import reports when it ignores it.
Source Files
¶
- access.go
- accesscode.go
- actionscache.go
- agyhook.go
- args.go
- backup.go
- bundle_secret.go
- capability_serve.go
- capability_servers.go
- change_target.go
- ci.go
- cicmd.go
- cicmd_print.go
- ciretrigger.go
- cliconn.go
- codex_detached.go
- connections.go
- context.go
- controller.go
- credentials.go
- credsource.go
- customfields.go
- daemon.go
- daemon_disk_floor.go
- daemon_envdefault.go
- daemon_local.go
- daemon_removed_settings.go
- daemon_restarts.go
- daemon_reviewed_merge.go
- daemon_unknown_flags.go
- db_check.go
- declcmd.go
- demo.go
- deployment.go
- errors.go
- export.go
- externalcmd.go
- failures.go
- fscmd.go
- gcpkey.go
- ghwebhook_flags.go
- grainimage.go
- health.go
- host_enroll.go
- hostd.go
- hostds.go
- hub.go
- hub_conn.go
- hub_delegation.go
- hub_manage.go
- hub_query.go
- import.go
- init.go
- init_prompter.go
- init_workstation.go
- list.go
- login.go
- main.go
- mcp_external.go
- mcp_external_ops.go
- mcpserver.go
- mergequeue.go
- metrics.go
- modelproxy.go
- packagecache.go
- pause.go
- prcmd.go
- printer.go
- priorityflag.go
- qa.go
- release.go
- releasenotes.go
- renamed_flags.go
- repo.go
- repocase.go
- repoprint.go
- runhost.go
- sandbox_budget_cmd.go
- sandbox_probe_cmd.go
- sandboximage.go
- sandboxnet.go
- schemaupgrade.go
- schemaversion.go
- secrets.go
- secretsrepo.go
- settingscmd.go
- settingsprint.go
- setup.go
- skill.go
- state.go
- state_wrap.go
- statemanager.go
- stateprepare.go
- statepullrequests.go
- staterepo.go
- stateresets.go
- stringsliceflag.go
- sync.go
- task_owner.go
- taskattributes.go
- taskcmd.go
- taskcontext_cmd.go
- taskfilters.go
- taskprint.go
- taskverbs.go
- upgrade_cmd.go
- upgrade_postgres.go
- usage_cmd.go
- version.go