lc status

Report what state each of the analysis's outputs is in. Reads only: it runs nothing, commits nothing, transfers no data, does not mind an unclean tree, and always exits 0: a state is not a failure. The moment you most need to know where a project stands is when it isn't clean, so this verb works there.

SynopsisCopy Anchor Link

lc status [OPTIONS]

OutputCopy Anchor Link

  mode:    direct
  sandbox: landlock (fs: declared, network: allowed)

  · current   baseline/fit       a3f1f11
  · current   baseline/fit_plot  a3f1f11
  · behind    robust/fit         00cc14e  made under an earlier environment
  ! stale     robust/fit_plot    —        no manifest — it has never been materialized
  · no recipe baseline/summary   —

2 current · 1 behind · 1 stale · 1 no recipe

The header is repository facts: which mode the project executes in (and, for a containerized project, the image's tag and state), and what enforcement a run on this host would get. No runtime and no network is needed to answer either.

Then one line per output the spec declares, in dependency order: its state, the commit it was made at, and, for anything not current, why. The commit column is the verb's reason to exist: "which code made this?" has an answer for a current output too, and for a behind output that commit is where the environment that produced it can be read back.

StatesCopy Anchor Link

• current: exactly what the spec asks for. Nothing to do.
• behind: still what the spec asks for; the environment moved since. Left alone by runs; --refresh remakes.
• stale: contradicts the project: definition changed, an input's content changed, or the output was edited by hand since it was made (a foreign write; the offending commit is named).
• no recipe: declared by the spec, but with no recipe to make it. Runs skip it, and lc materialize --check passes over it. Write its recipe to make it.

Report vs gateCopy Anchor Link

lc status reports; lc materialize --check gates. Two verbs answering the same question with different exit codes is how a script comes to depend on the wrong one, so the split is sharp: use status for eyes, check for exit codes.

The gate covers only outputs that have a recipe, because it predicts what a run would do and a run skips the rest. An analysis is finished when the check passes and status lists no no recipe output.

OptionsCopy Anchor Link

The JSON reportCopy Anchor Link

{
  "mode": "direct",
  "image": null,
  "sandbox": "landlock (fs: declared, network: allowed)",
  "counts": {"current": 4, "behind": 0, "stale": 0, "no recipe": 0},
  "outputs": [
    {
      "output": "baseline/fit",
      "status": "current",
      "why": "",
      "git_sha": "a3f1f11791430d1becbe5548477b5910ab59a94a",
      "data_version": "sha256:939e9a55...",
      "foreign_write": ""
    }
  ],
  "warnings": []
}

Per output: the state, the reason (empty for current and no recipe), the commit it was materialized at and its content identity (both empty if it never was), and foreign_write: the sha of a hand-edit's commit when one was detected, which the prose why cannot carry for a machine consumer. For a containerized project, image is {"tag": ..., "state": "present" | "absent" | "unfetched"}.