CLI commands¶

Global options¶

These go before the command, for example forest -C ../other push.

Option	Effect
`-C PATH`	Run as if started in `PATH`.
`--verbose`	Detailed output.
`--quiet`	Errors only.
`--color` / `--no-color`	Force rich or plain output. Default: rich on a TTY, plain when piped. `--help` ignores them; use `NO_COLOR` or `FORCE_COLOR`.
`--version`	Print the version.
`-h`, `--help`	Help for any command.

Selectors¶

push, pull, status, diff and flow take positional selectors:

forest pull                       # every bound stage
forest pull sorting               # one stage (branch)
forest pull sorting/Sort_A        # one unit
forest pull sorting/Sort_A sorting/Sort_B   # several units, same branch
forest pull --id Sample_01        # units listed for an ID in the manifest
forest pull sorting --id Sample_01          # same, only the sorting stage

All qualified units in one call must belong to one branch, and they cannot be combined with --id. Bare push and pull skip unbound stages with a warning, and stages whose direction forbids the verb. A stage you name must be bound and allow that direction.

Workspace and checkouts¶

Command	Effect
`forest init`	Create `.forest/`. Inside an existing workspace, reports setup status.
`forest checkout NAME`	Switch to `NAME`, creating it first if it is new.
`forest checkout create NAME`	Create and switch to `NAME`.
`forest checkout list`	List checkouts; `*` marks the active one.
`forest checkout current`	Print the active checkout name.
`forest checkout remove NAME [--yes]`	Remove checkout metadata. `--yes` skips the prompt.

Remotes¶

Command	Effect
`forest remote add NAME URL`	Add a workspace remote. `URL` is an absolute local path, `s3://bucket/prefix`, `sftp://host/path` or `user@host:/path`.
`forest remote use NAME`	Remote that new checkouts will save. Existing checkouts keep theirs.
`forest remote list`	List remotes.
`forest remote show NAME`	Show one remote.
`forest remote remove NAME`	Remove a remote.

remote add options:

Option	Effect
`--region TEXT`	S3 region, e.g. `us-east-2`.
`--endpoint TEXT`	S3-compatible endpoint URL (non-AWS).
`--profile TEXT`	S3 auth profile name.
`--key-file TEXT`	SFTP private key file. Required for SFTP.
`--known-hosts TEXT`	SFTP `known_hosts` file. Required for SFTP.

Stages and bindings¶

Command	Effect
`forest add STAGE PATH [REMOTE:PATH]`	Register `STAGE` in the active checkout and bind it to local `PATH`. `REMOTE:PATH` saves `PATH` as the stage's `remote_path`; `REMOTE` must be the checkout's remote. Default `<checkout>/<stage>`.
`forest bind`	List bindings.
`forest bind STAGE PATH`	Bind an existing stage to a local path, for example on a fresh clone.
`forest unbind STAGE`	Remove a local binding.

add options:

Option	Values	Default
`--direction`	`push`, `pull`, `both`	`both`

Transfers¶

forest push [SELECTORS] and forest pull [SELECTORS]

Option	push	pull	Effect
`--id TEXT`	yes	yes	Resolve units through the manifest.
`--dry-run`	yes	yes	Show the plan, transfer nothing.
`--no-verify`	yes	yes	Skip the post-transfer check against the remote.
`--force`	yes	yes	push: overwrite remote files changed since the last sync. pull: overwrite local files changed since the last sync.
`--exclude TEXT`	yes		Glob to leave out, relative to the unit. Repeatable.

Transfers include every file in a unit except files named .DS_Store, ._*, *.tmp and *.forest-tmp; push counts each file it leaves out, names the first ten (--verbose names all) and warns about stage-root entries outside any unit. Push stores each symlink as an rclone link file, <path>.rclonelink, that holds the link's target, and never follows a directory symlink. Broken links, absolute links, links that leave the stage, unit folders that are symlinks, real files named *.rclonelink and links to unit paths the push leaves out fail the unit; --exclude them to push the rest. Pull recreates each link file as its symlink. It refuses absolute targets, targets that leave the stage, and a remote path that holds both a link file and data. It makes the empty folder a link points at when the target is in the unit and nothing is stored at or under it. Pull writes partial files as *.forest-tmp and renames them when done. Forest ignores leftover partial files but does not delete them. To recover from a refused push or pull, see Sync recovery.

Inspect¶

Command	Effect
`forest status [SELECTORS]`	Compare local files with the checkout's saved remote. Transfers nothing. Symlinks compare as their link files (`<path>.rclonelink`), as push stores them.
`forest diff [SELECTORS]`	Files `added`, `deleted` or `modified` (size changed) since the last push. An edit that keeps the size shows nothing; `status --checksum` catches it.
`forest flow [SELECTORS]`	Print a Mermaid diagram of the checkout's stages.

status options: --id TEXT, --checksum (compare hashes, slower), --incomplete (hide synced rows).

status rows are synced, different, local-only and remote-only, each followed by the remote name. Saved sync history can refine a row to local-changed, local-missing or remote-missing, and with --checksum to remote-changed. different means the files differ but forest cannot tell which side changed.

$ forest status raw
synced:origin  raw/run1/a.txt  matches remote
synced:origin  raw/run1/b.txt  matches remote
local-changed:origin  raw/run1/c.txt  absent on remote

flow options: --id TEXT, --direction LR|TD (default LR), --output PATH (write to a file instead of stdout).

Shell prompt¶

eval "$(forest prompt init zsh)"   # or bash

See Shell prompt.

Requirements¶

Transfers and status need rclone on PATH. status needs rclone 1.71 or later and asks you to upgrade on older versions. CI uses 1.75.1.