Command reference

Every command, every flag.

Global options come before the command: secretree [-C <dir>] [-v] <command> [options]. -C runs as if started in that directory; -v prints progress details. Every command accepts -h. Flags may follow positional arguments.

init

secretree init --vault <url|dir|github:owner/name|gitlab:owner/name>
               [--kit-out <file>] [--push] [--label <name>] [--remote origin]
               [--from-recovery-kit <file>] [--repo-id <id>] [--no-remote] [--force]

Prepares the current repository for a vault. An empty remote becomes a new vault (fresh keys, recovery kit); a remote that already is a vault is joined with the keys in the key store or from --from-recovery-kit. github: and gitlab: prefixes create a private repository through the gh or glab CLI. Installs the helper and adds the --remote (default origin) unless --no-remote; --push pushes every branch and tag at once. --label is the name stored (encrypted) in manifests, default the directory name. --repo-id continues an existing chain. --force re-initialises.

kit

secretree kit --print <file> | --confirm

--print sends the recovery kit to the default printer (lp) or opens the file; --confirm records that it is on paper so status stops warning.

backup

secretree backup [--full]

Snapshots every ref and the configured state archive into one generation, pushes it, and runs the restore proof. Details in Backup, verify, restore.

verify

secretree verify [--generation N] [--quick] [--all]

Fresh clone of the vault, full chain verification, rebuild of generation N (default latest). --quick skips the rebuild; --all hashes every ciphertext of every generation.

restore

secretree restore --vault <url|dir> --to <dir> [--repo-id <id>] [--generation N]
                  [--from-recovery-kit <file>] [--no-state]

Rebuilds a repository and its state archive into a new directory and configures it to continue the same chain.

status

secretree status

Repository, vault, key store state, generations and size, last backup, last proven generation, state archive configuration, the last error, and warnings about an unconfirmed recovery kit or an unproven generation.

doctor

secretree doctor

Checks git, the helper, the key store, the repository configuration, the vault and its chain, the recovery kit, the restore proof, the policy, the pipeline and the local UI, and prints the fix next to every failure. Exit status 1 when something failed. The first thing to run when anything looks off.

demo

secretree demo [--dir <dir>] [--clean]

Runs the full walkthrough on a throw-away vault with a file key store and leaves the UI running; --clean removes it. Needs a POSIX shell (WSL on Windows).

clone

secretree clone <vault-url> [dir] [--repo-id <id>] [--from-recovery-kit <file>]

Imports the kit when given, makes sure the helper is reachable, then runs git clone secretree::<vault-url>[#<repo-id>].

install-helper

secretree install-helper [--dir <bindir>]

Creates git-remote-secretree (symlink or copy of the binary) in --dir, default the binary's own directory, and tells you if that directory is not on PATH.

schedule

secretree schedule --every <duration> | --daily HH:MM | --remove | --show

Installs, shows or removes a launchd agent (macOS) or a systemd user timer (Linux) that runs secretree backup for this repository.

join

secretree join --vault <url|dir> [--name <device>] [--out <file>]

Generates keys for the vault on this device and prints or writes the join request.

member

secretree member list
secretree member add --request <file> [--role agent] [--name <n>]
secretree member add --recipient age1… [--signer "ssh-ed25519 …"] --name <n> [--role agent]
secretree member remove --name <n> | --recipient age1…
secretree member request

add re-signs vault.json and writes a full generation to the new recipient set; remove revokes the signer with a cut-off and writes a full generation to the remaining set. request prints this device's join request.

pr

secretree pr open [--title <t>] [--body <text>] [--head <branch>] [--base <branch>]
secretree pr list [--all]
secretree pr show <#n>
secretree pr diff <#n> [--stat]
secretree pr checkout <#n>
secretree pr comment <#n> -m <text> [--path <file> --line <n>]
secretree pr approve <#n> [-m <text>]
secretree pr request-changes <#n> -m <text>
secretree pr review <#n> --verdict approve|request_changes|comment [-m <text>]
secretree pr resolve <#n> <comment-id>
secretree pr merge <#n> [--method merge|squash|ff]
secretree pr close <#n>

open pushes the head branch first when it is not on the vault yet. Details in Pull requests and reviews.

policy

secretree policy [--approvals 1] [--checks ci,lint]

Writes .secretree/policy.json; commit it on the base branch. --checks "" requires none.

runner

secretree runner [--name ci] [--cmd <command>] [--branches main] [--interval 60s] [--timeout 30m] [--once]

CI agent; see CI and deploy. --branches "" restricts it to pull requests.

deploy-agent

secretree deploy-agent --to <dir> [--branch main] [--cmd <command>] [--require-check ci] [--interval 60s] [--once]

Pull-based deploys gated on a green check.

share

secretree share <path> [--ref <ref>] [--expires 7d] [--note <why>] [--out <file.html>] [--no-ledger]
secretree share --diff <a..b>|<commit> [--expires 7d] [--note <why>] [--out <file.html>]

Encrypted, self-contained share page; every share is a ledger entry unless --no-ledger (not recommended).

ledger

secretree ledger
secretree ledger add --kind share|export|public-mirror --subject <what> [--note <why>]

ui

secretree ui [--listen 127.0.0.1:7391] [--open]
secretree ui --install [--listen …] | --uninstall

link

secretree link <path>[:<line>] [--ref <ref>]

Prints a permalink into the local UI, pinned to the current commit unless --ref is given.

watch

secretree watch --ntfy <url> | --desktop | --exec <command> [--serve :8787] [--include-titles] [--interval 2m] [--once]

version

secretree version

Environment

Files