docs/cli.md and the binary disagree on the unattended flag, and omit the variable that controls audit commands

[vladimirrott]

Four gaps between docs/cli.md and what an operator actually gets, found by building a real nightly job from the docs alone.

1. --help and docs/cli.md state different contracts for --dangerously-skip-approval

--help says:

Implies --yes, --max-risk high and --non-interactive unless you set a lower --max-risk, which still wins.

docs/cli.md says:

--yes may now auto-approve HIGH-risk steps. The cap moves from MEDIUM to HIGH.

The second reads as though --yes still has to be typed, and never mentions --non-interactive at all. That difference changes what a script must pass, and it changes what --step-by-step combined with the flag does. Whichever is right, the other has to move.

2. The flag gates and banners subcommands that approve nothing

$ SYSKNIFE_I_ACCEPT_UNATTENDED_ROOT=1 sysknife audit export --dangerously-skip-approval
[]
  (full UNATTENDED MODE banner on stderr)

$ sysknife doctor --dangerously-skip-approval      # env var unset
sysknife: --dangerously-skip-approval was passed but SYSKNIFE_I_ACCEPT_UNATTENDED_ROOT is not set to 1.
$ echo $?
1

This is deliberate, and the reason is in the source: a flag that is sometimes silently ignored teaches people it is harmless. But docs/cli.md frames the whole section around plan execution, and the only hint is one line under Global flags saying all flags apply to every subcommand.

A wrapper that uniformly appends the flag to every invocation, which is a normal "always non-interactive" pattern, gets hard refusals on health checks and audit shipping. Say so in the Unattended mode section.

Stream separation is correct here: the banner is on stderr and stdout stays clean, so jq still parses. Only the scope is undocumented.

3. SYSKNIFE_DATABASE_PATH is missing, and SYSKNIFE_SOCKET does nothing for audit commands

$ grep -c SYSKNIFE_DATABASE_PATH docs/cli.md
0

developer-guide.md and the-audit-chain.md both document it as the way to point audit export and audit verify at a specific store, including a copied remote database. docs/cli.md's own Environment variables section never mentions it.

Worse, the reverse is implied. SYSKNIFE_SOCKET has its own entry warning about forwarded sockets, and audit verify --pubkey is described as the auditor path, so pointing SYSKNIFE_SOCKET at a particular daemon looks like it selects which trail you export. It does not. Audit commands never dial the daemon; they read a local file. In a fleet with several daemons that is a silent wrong answer.

4. --log-to is a stdout-only tee, and the doc's own example produces an empty file on failure

Running docs/cli.md's own Scripting and CI example verbatim, on a run that failed:

$ cat /tmp/.../nightly.log
        # 0 bytes

Every diagnostic line goes to stderr: the provider fallback notice, the planning status, and the final error. --log-to tees stdout only. On the one occasion an operator needs the log, it is empty, and nothing in the section says to capture stderr separately.

Scope

All four are docs/cli.md, except #1 which needs someone to decide which of the two statements is true and correct the other.

Difficulty

easy. Four sections of one file, plus reading main.rs once to settle #1.

Getting started

CONTRIBUTING.md has the build and test commands. docs/cli.md is not in the CI markdownlint list, so check it with npx markdownlint-cli2 docs/cli.md before pushing. No CLA and no copyright waiver. The project is MIT.

[vladimirrott]

@Osheun this one is close to your #259, if you want it.

Four places where docs/cli.md and the binary disagree. The sharpest is #3 in the body: SYSKNIFE_DATABASE_PATH is what actually selects which store audit export and audit verify read, and it appears nowhere in docs/cli.md, while SYSKNIFE_SOCKET has its own entry that implies it matters for those commands. It does not. On a host with several daemons, pointing SYSKNIFE_SOCKET at one of them and running audit export gives you a different trail with no warning.

Your #259 fixed a claim-screening script that was reading the wrong list of files. This is the same shape in prose: a documented variable that does not control what the reader thinks it controls.

There is an option worth considering while you are in there. scripts/check_evidence_claims.py already screens sixteen files for claims that must match evidence. A rule that every SYSKNIFE_* variable read by the CLI appears in docs/cli.md's environment table would stop the next one going missing. That is optional and the docs fix stands alone.

Interested?

[Osheun]

Yes, I’m interested. I’ll take a look and work on it this evening or tomorrow. Thanks for pointing it out!

[vladimirrott]

Checking in, and nothing is owed. You took this on 1 September and I have not
seen a branch. The issue has not moved and nobody else has started it.

Two things, in case either is what stalled it.

Gap 1 asked you to decide something I should have decided. The issue says
"whichever is right, the other has to move" and left you to work out which.
--help is the wrong one. The flag implies none of the three things it claims:

$ git rev-parse --short=8 HEAD
adab560d
$ sed -n "186,194p" apps/sysknife-cli/src/main.rs
        yes: cli.yes,
        max_risk: cli.max_risk.map(crate::approval::MaxRisk::from),
        non_interactive: cli.non_interactive,
        dry_run: cli.dry_run,
        json: cli.json,
        step_by_step: cli.step_by_step,
        skip_approval: crate::cli::UnattendedConsent::from_env(cli.dangerously_skip_approval)
            .is_granted(),
    }
$ grep -rn "\.yes = \|non_interactive = \|max_risk = " apps/sysknife-cli/src/
(exit 1)

Those three fields come straight off the parsed flags, and nothing else in the
crate writes them. With --yes absent the ceiling is None before
skip_approval is ever consulted:

$ sed -n "132,135p" apps/sysknife-cli/src/approval.rs
    pub fn effective_auto_ceiling(&self) -> Option<MaxRisk> {
        if !self.yes {
            return None;
        }

So docs/cli.md:346 is right, and apps/sysknife-cli/src/cli.rs:62-68 is the
text that moves. One more place carries the same wrong claim and should move
with it, because it is the comment that would talk the next reader out of the
fix:

$ sed -n "250,254p" apps/sysknife-cli/src/approval.rs
    #[test]
    fn the_override_is_inert_without_yes() {
        // The flag implies --yes at the CLI layer. If that wiring is ever
        // dropped, the policy must not auto-approve on the override alone.

The test is correct and its comment describes wiring that was never there.

If you would rather wire the implication than correct the sentence, say so here
first. Widening what one flag auto-approves is a change I want to argue about
before it lands, and reading --help and believing it is not a mistake on your
side.

Nothing has moved under you. All four gaps still reproduce at adab560,
including the one that looks most likely to have been fixed by someone else:

$ grep -c SYSKNIFE_DATABASE_PATH docs/cli.md
0

docs/cli.md was edited twice since you claimed this, by #348 and #381, and
neither commit changed any of the four.

The claim is yours until you tell me otherwise, and dropping it costs nothing.
Say the word and it goes back in the pool with no hard feelings. If something in
the issue text did not match what you found, tell me and I will fix the text
rather than leave you working around it.

[vladimirrott]

@Osheun releasing this one, and there is nothing owed either way.

You took it on 1 September and I checked in on the 8th with the decision the
issue should have made for you in the first place. Nothing since, so I am
putting it back in the pool rather than leaving it parked with your name on it
where other people can see it and stay off.

It is yours again whenever you ask. One sentence here and the label and the
assignment go straight back on.

Nothing has moved under you in the meantime. All four gaps still reproduce at
current main:

$ git rev-parse --short=8 HEAD
61b3a878
$ grep -c SYSKNIFE_DATABASE_PATH docs/cli.md
0
$ sed -n '63,68p' apps/sysknife-cli/src/cli.rs
    /// Execute HIGH-risk steps with no human confirmation.
    ///
    /// Requires `SYSKNIFE_I_ACCEPT_UNATTENDED_ROOT=1` in the environment as
    /// well; the flag on its own refuses to run. Implies `--yes`,
    /// `--max-risk high` and `--non-interactive` unless you set a lower
    /// `--max-risk`, which still wins.

So the answer in my check-in still stands: that doc comment is the text that
moves, and docs/cli.md is right.

Your #259 is why check_evidence_claims.py reads the file list it was always
meant to read. Come back for anything on the tracker when you have an evening
for it.

[vladimirrott]

@kragent66-glitch, it has been a while since #285, and this is an easy way back in if you want it.

docs/cli.md and the binary disagree about the unattended flag, so somebody reading the documentation types a flag the CLI rejects.

Small and self-contained. The one decision worth making is which of the two is wrong, so check the binary before you change the docs.

No deadline. If you would rather have something with more code in it, say so and I will find you one.

[vladimirrott]

@kragent66-glitch withdrawing this offer, and the timing was my error rather than yours.

I put it in front of you yesterday at 11:26Z. @armutlutost opened #436 against it under four hours later, and that PR is in review now, so the work is gone. You had not replied and nothing is owed; I would rather tell you today than leave you to find out by opening the file.

I have offered you a different one on #218, chosen to be closer to #285 than this was.