Run sapling alone in a project directory for the default interactive session - that one command is the only thing you actually need. Everything below is either what that default session offers to do for you inline (logging in, picking a model), or an optional subcommand for something more specific.
sapling
Starts an interactive pair-mode session in the current directory (full-screen TUI if stdout is a real terminal, a plain REPL otherwise). If nothing's usable yet - not logged in, no provider registered - it opens the same menu /model does, right there, with “Log in to Sapling” as the first option. This one command is the entire golden path.
sapling init
Creates a starter .sapling/config.toml in the current git repo. Optional - sapling will offer to do this for you on first run in a new project too.
sapling login
Log in to your Sapling account directly, without starting a session. Equivalent to picking “Log in to Sapling” from the in-session menu - never required on its own, just available if you'd rather log in before your first real session.
sapling update
Check for and install a newer build right now, regardless of whether the current release is marked force-update. No-op on a dev/pip install (nothing to self-replace).
sapling --version
Print the running build's version and exit - doesn't trigger an update check.
sapling auth login [--provider ID]
Register a model provider directly (BYOK) - a thin wrapper over OpenCode's own auth, for providers you want to bring your own key for outside a Sapling account. The in-session /model menu offers this same flow (“+ Register a new provider”) without leaving your session.
sapling auth list
List currently registered/connected providers.
sapling autonomous [--minutes N] [--dollars N] [--from-node ID] [--max-turns N] [--extended] [--max-cycles N]
Bounded-autonomous mode: branch and prune a hypothesis tree off a time/dollar budget instead of a single interactive turn. --extended chains bounded cycles within the budget, each continuing from the last cycle's winner.
sapling log show [--node ID]
Inspect the Research Log - the active path by default, or one specific node by id.