Skip to main content
A project is the spine. Milestones group work inside it, tasks are the units, and both address their parent by slug or by display name.

​
Creating a project

Why it works. --path is what connects the project to a folder, which is what lets a path trigger fire when you work in it. A project without a path still exists, it just has no way to notice you are working on it. The gotcha. If you omit --path and the protocol configuration is not enabled, the project has no folder at all. base project list --unscoped finds these later, and they are usually a mistake rather than a choice.

​
Milestones and tasks

Why it works. A task carries a project edge and, optionally, a milestone edge. They are separate edges, which is why reassigning one leaves the other alone. Next rung. base task tag <slug> --add urgent attaches free-form labels, and base task list --label urgent --label backend narrows to tasks carrying all of them. Repeating --label intersects rather than unions.

​
Editing instead of recreating

Why it works. Every update is addressed by slug or display name and rewrites only the fields you named. Moving a task to a different milestone rewrites the milestone edge and leaves the project edge untouched. The gotcha worth acting on. --next-action is the field that decides whether a project is resumable. A project with a status and no next action tells you it is alive and nothing else.

​
When a folder moves

Both arguments are positional: slug, then the new path. Why it works. This updates the graph and the domain trigger together. A path trigger pointing at a folder that no longer exists is a domain that silently stops firing, and nothing will tell you. The gotcha. Do this whenever a folder moves, even if the project still “works”. The failure is silent and looks like base having stopped caring about that project.

​
One project, two workspaces

Why it works. This adds a link rather than copying anything. The project lives in one place, and an edit from either workspace edits the same project. To move it outright:
It takes the project’s tasks, its domain, and its decisions, rules and notes with it, and regenerates the code map at the destination rather than carrying stale paths across. It prints the plan and changes nothing without --yes.

​
Finding a project you cannot find

The gotcha. base project list shows the current workspace only. A project missing from it is usually a project that now lives in another workspace, not a project that is gone. Check --all before concluding anything.

​
Deleting, and what goes with it

All three preview by default and change nothing until --yes. The gotcha. project delete --force takes the decisions and rules as well, and those are usually the part you would actually miss. The tasks are replaceable; the reasoning behind a choice made eight months ago is not.

​
Bringing state back in line

This reads each project’s folder for when it was last touched and updates its active or deferred state to match. The gotcha. Run --dry-run first, always. It decides from filesystem activity, so a project you have been working on outside its registered folder looks dormant when it is not.

​
Next

Multiple sessions

Coordinating when more than one session is working the same project.

Projects reference

Every flag on every command here.