Onset command reference

Every command saves the workspace before it does anything else, takes --json, and ends with a next: line when there's something to do. on help <command> prints a command's options.

Commands

Group	Command	What it does
Start	on get <project> [folder]	Makes a workspace for a project. --lazy fetches each file when it's first opened.
	on init [folder]	Starts a project that lives only on this machine.
	on import <git-repo> [folder]	Makes a project from a Git repository, with its history.
	on publish <project>	Puts a local project on a host.
	on login [host]	Signs in. The default host is upstream.codes.
	on workspaces [add <folder> | clean]	Lists this project's workspaces, adds one or removes the finished ones.
	on mount [folder]	Starts a lazy workspace's mount again. --stop stops it.
See	on status [change]	Where you are and what to do next.
	on diff [path...]	What a change changes.
	on log [version|change|path]	History of main, open changes, saves or operations.
	on blame <file>	The version that last changed each line.
	on show <file>	Prints a file as it is in main, or --from a version, change or save.
	on bisect <good> <bad> --run "<command>"	Finds the first version of main where a command fails.
	on verify [version]	Who signed the land that made a version.
	on git	Where Git clones the project, and whether the Git view is current.
Work	on new ["title"]	Starts another change. The current one is kept.
	on describe "text"	Sets the current change's description.
	on switch <change>	Puts this workspace on another change.
	on drop [change]	Abandons a change.
	on tag [name] [version]	Names a version of main. --remove takes the name off.
	on line [name]	Lists release lines, or starts one --from a version.
Finish	on sync	Brings the change up to date with main.
	on land [change]	Puts a change on main.
	on watch --run "<check>"	Checks each new version of main and takes back the one that breaks the check.
Fix	on undo [version]	Undoes the last on command, or takes a landed version back out.
	on restore <path...>	Brings files back from an earlier point.
	on purge <path>...	Takes files out of the project's whole history. Owners only.
	on rollback --to <time>	Puts a hosted project back as it was. Owners, the last 30 days.
	on check	Checks this machine's objects and the host's copy for damage.
	on gc	Cleans up old saves and objects on this machine.
Share	on access <change|path> [who...]	Shows or sets who can see a change or a path.
	on group <name> [@person...]	Shows or sets one of the project's groups.
	on approve <change>	Approves someone else's change.
	on key	Makes this machine's signing key. Lands are signed from then on.
	on settings [name=value]	Shows or sets host settings: approvals=N, git=on|off, signed=required|optional.
	on sessions	Agent sessions kept with changes: list, show, turn off or delete.
	on submodule	Lists, adds, removes or checks out Git submodules.
Help	on guide	Prints the guide for coding agents.
	on help [command]	Help for a command.

References

Written	Means
48213	Version 48213 of main. main is the latest version.
rtnbkcvx or rtnb	A change at its latest save. The first four letters or more are enough.
rtnb:14	Save 14 of change rtnb.
1.x, 1.x/3	A release line at its latest version, and its version 3.
--at "10 min ago", --at 15:30	A point in time in this workspace's saves.

onset.toml

Optional, at the project's root. It lands like any file.

[workspace]
copy = ["node_modules", "target"]    # build folders new workspaces copy from your latest one

[mine]
paths = [".env", ".env.*", "!.env.example", "!.env.sample", "!.env.template"]   # the default

[land]
run = ["pnpm lint", "pnpm test"]     # on land runs these first. If one fails, nothing lands

[land] run belongs to each machine, as Git hooks do. Required checks, approvals and who can land are host settings, so a change can't loosen its own rules.

Environment variables

Variable	Does
ONSET_TOKEN	Signs in with a token, for agents and CI.
ONSET_NAME, ONSET_EMAIL	The author of lands made with on land.
ONSET_SAVER=0	Turns the background saver off.
ONSET_SESSIONS=0	Doesn't keep the agent's session for this command.
ONSET_GIT=0	Makes workspaces without a .git.
ONSET_UPDATE_CHECK=0	Turns off the daily look for a new release.
ONSET_HOME	Where Onset keeps its data. The default is ~/.local/share/onset.

Limits

	Limit
One project	100 GiB
One file	5 GB. Files over 1 MiB are stored in chunks, so a small edit uploads only what changed.
One HTTP edits call	10,000 files
Rollback	The last 30 days
Saves of a landed or dropped change	Kept for 30 days

Onset runs on macOS, Linux and Windows, on x64 and arm64.