> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Commands for the work itself: projects and the milestones and tasks under them, plus goals, reminders, the people and organizations attached to them, and the reconcile that reads real folder activity back into project state.

Projects are the spine. A milestone is a chunk of a project, a task is a unit of work in one, and both address their parent by slug or by display name. Goals, reminders and entities hang off the same graph without belonging to that hierarchy.

Every one of these commands takes a short alias: `base p` for `project`, `m` for `milestone`, `t` for `task`, `g` for `goal`, `r` for `reminder`, `e` for `entity`. Verbs alias too, so `base p l` is `base project list`.

<Warning>
  The four delete commands here (`project delete`, `milestone delete`, `task delete` and `reminder remove`) remove data. Three of them print a plan and change nothing until you pass `--yes`. `base reminder remove` is the exception: it deletes immediately.
</Warning>

## Projects

### base project add

Register a new project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project add --name "basemode docs"
base project add --name "basemode docs" --path "docs" --status active
base project add --name "basemode docs" --stage build
```

| Flag                | Short | What it does                                                              |
| ------------------- | ----- | ------------------------------------------------------------------------- |
| `--name <NAME>`     | `-n`  | The project's display name. Required.                                     |
| `--status <STATUS>` | `-s`  | Status. Defaults to `active`.                                             |
| `--path <PATH>`     | `-p`  | The project's folder, relative to the workspace.                          |
| `--stage <STAGE>`   |       | Which lifecycle stage the project starts in. Defaults to the first stage. |

If you leave `--path` out and the protocol configuration is enabled, the folder is derived from the stage and created for you. If it is not enabled, the project has no folder, which is what `base project list --unscoped` finds later.

### base project list

List projects. By default it shows the current workspace only.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project list
base project list --all
base project list --workspace basemode
base project list --unscoped
base project list --json
```

| Flag                      | What it does                                         |
| ------------------------- | ---------------------------------------------------- |
| `--all`                   | Every registered workspace, as one flat list.        |
| `--workspace <WORKSPACE>` | Only projects homed in the named workspace.          |
| `--unscoped`              | Only projects with no folder and no registered home. |
| `--json`                  | Emit JSON on a stable contract, instead of a table.  |

Reach for `--all` before concluding a project has disappeared. Projects move between workspaces, and a project missing from the current workspace is usually a project that now lives somewhere else.

### base project get

Show one project in full. Accepts the slug or the display name.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project get basemode-docs
base project get "basemode docs" --json
```

| Flag     | What it does                                        |
| -------- | --------------------------------------------------- |
| `--json` | Emit JSON instead of the human-readable field list. |

### base project update

Change a project's mutable fields.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project update basemode-docs --status active
base project update basemode-docs --blocked-by "reference block merge"
base project update basemode-docs --next-action "write the guides"
```

| Flag                          | Short | What it does                   |
| ----------------------------- | ----- | ------------------------------ |
| `--status <STATUS>`           | `-s`  | The project's status.          |
| `--blocked-by <BLOCKED_BY>`   | `-b`  | What is holding it up.         |
| `--next-action <NEXT_ACTION>` |       | The next concrete thing to do. |

`--next-action` is the field worth keeping current. It is the difference between a project you can resume and a project you have to reconstruct.

### base project peer

Make a project surface in another workspace as well as its own, without moving it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project peer basemode-docs --workspace chris-ai-systems
base project peer basemode-docs --workspace chris-ai-systems --remove
```

| Flag                      | Short | What it does                                      |
| ------------------------- | ----- | ------------------------------------------------- |
| `--workspace <WORKSPACE>` | `-w`  | The workspace it should also appear in. Required. |
| `--remove`                |       | Take the peer link off instead of adding it.      |

This adds a link, it does not copy anything. The project still lives in one place, and edits from either workspace are edits to the same project.

### base project repath

Re-point a project at its new folder after you move it on disk. This updates the graph and the domain trigger together.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project repath basemode-docs "~/basemode/docs"
```

Both arguments are positional: the slug, then the new path, absolute or relative to the workspace root. Do this whenever a folder moves, because a path trigger pointing at a folder that no longer exists is a domain that silently stops firing.

### base project move

**Destructive. Preview by default.** Re-home a project into another workspace's graph, taking its tasks, its domain, and its decisions, rules and notes with it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project move basemode-docs --to basemode --dry-run
base project move basemode-docs --to basemode --yes
base project move basemode-docs --to basemode --no-ast --yes
```

| Flag        | What it does                                                        |
| ----------- | ------------------------------------------------------------------- |
| `--to <TO>` | Destination workspace name, as registered in `base.toml`. Required. |
| `--dry-run` | Print the plan and write nothing.                                   |
| `--no-ast`  | Skip regenerating the code map at the destination.                  |
| `--yes`     | Apply the move. Without it, you get the plan and nothing changes.   |

The code map regenerates at the destination rather than travelling, which is why the paths come out right. Pass `--no-ast` only if you intend to run `base sync --ast` there yourself.

### base project delete

**Destructive. Preview by default.** Delete a project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base project delete basemode-docs
base project delete basemode-docs --yes
base project delete basemode-docs --force --yes
```

| Flag      | What it does                                                         |
| --------- | -------------------------------------------------------------------- |
| `--force` | Cascade-delete the project's tasks, milestones, decisions and rules. |
| `--yes`   | Apply the delete. Without it, you get the plan and nothing changes.  |

Without `--force` it refuses a project that still has children, which is the guard rail. With `--force` it takes them all, and the decisions and rules go too, and those are usually the part you would actually miss.

## Milestones

### base milestone add

Add a milestone to a project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base milestone add --project basemode-docs --name "Reference block"
base milestone add --project basemode-docs --name "Reference block" --description "Seven pages, 120 command paths"
```

| Flag                          | Short | What it does                            |
| ----------------------------- | ----- | --------------------------------------- |
| `--project <PROJECT>`         | `-p`  | Project slug or display name. Required. |
| `--name <NAME>`               | `-n`  | The milestone's name. Required.         |
| `--description <DESCRIPTION>` | `-d`  | What it covers.                         |

### base milestone list

List milestones, optionally within one project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base milestone list
base milestone list --project basemode-docs
base milestone list --json
```

| Flag                  | Short | What it does                    |
| --------------------- | ----- | ------------------------------- |
| `--project <PROJECT>` | `-p`  | Only this project's milestones. |
| `--json`              |       | Emit JSON on a stable contract. |

### base milestone get

Show one milestone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base milestone get reference-block
base milestone get reference-block --json
```

| Flag     | What it does                                        |
| -------- | --------------------------------------------------- |
| `--json` | Emit JSON instead of the human-readable field list. |

### base milestone update

Change a milestone's status or description.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base milestone update reference-block --status completed
base milestone update reference-block --description "Seven pages, all three scripts green"
```

| Flag                          | Short | What it does            |
| ----------------------------- | ----- | ----------------------- |
| `--status <STATUS>`           | `-s`  | The milestone's status. |
| `--description <DESCRIPTION>` | `-d`  | What it covers.         |

### base milestone delete

**Destructive. Preview by default.** Delete a milestone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base milestone delete reference-block
base milestone delete reference-block --yes
base milestone delete reference-block --force --yes
```

| Flag      | What it does                                                        |
| --------- | ------------------------------------------------------------------- |
| `--force` | Delete the milestone's tasks as well.                               |
| `--yes`   | Apply the delete. Without it, you get the plan and nothing changes. |

By default the tasks survive: they are detached back to the project rather than deleted with their milestone. `--force` is what turns this into a cascade.

## Tasks

### base task add

Add a task to a project, optionally under a milestone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task add --project basemode-docs --name "Write reference/setup.mdx"
base task add --project basemode-docs --name "Write reference/setup.mdx" --milestone reference-block --priority high
```

| Flag                      | Short | What it does                            |
| ------------------------- | ----- | --------------------------------------- |
| `--project <PROJECT>`     | `-p`  | Project slug or display name. Required. |
| `--name <NAME>`           | `-n`  | The task's name. Required.              |
| `--priority <PRIORITY>`   |       | The task's priority.                    |
| `--milestone <MILESTONE>` | `-m`  | Group the task under this milestone.    |

### base task list

List tasks, filtered by project, milestone or label.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task list
base task list --project basemode-docs
base task list --milestone reference-block
base task list --label docs --label blocked
base task list --json
```

| Flag                      | Short | What it does                                             |
| ------------------------- | ----- | -------------------------------------------------------- |
| `--project <PROJECT>`     | `-p`  | Only this project's tasks.                               |
| `--milestone <MILESTONE>` | `-m`  | Only this milestone's tasks.                             |
| `--label <LABEL>`         |       | Only tasks carrying **all** of these labels. Repeatable. |
| `--json`                  |       | Emit JSON on a stable contract.                          |

Repeated `--label` narrows rather than widens: two labels means tasks carrying both, not either.

### base task get

Show one task, every field.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task get write-reference-setup-mdx
base task get write-reference-setup-mdx --json
```

| Flag     | What it does                                        |
| -------- | --------------------------------------------------- |
| `--json` | Emit JSON instead of the human-readable field list. |

### base task update

Change a task's mutable fields, including which project or milestone it belongs to.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task update write-reference-setup-mdx --status completed
base task update write-reference-setup-mdx --priority high --due 2026-08-26
base task update write-reference-setup-mdx --milestone guides-block
```

| Flag                          | Short | What it does                                 |
| ----------------------------- | ----- | -------------------------------------------- |
| `--name <NAME>`               |       | A new display name.                          |
| `--status <STATUS>`           | `-s`  | `active` or `completed`.                     |
| `--priority <PRIORITY>`       |       | The task's priority.                         |
| `--description <DESCRIPTION>` |       | Free-form notes. Also accepted as `--notes`. |
| `--assignee <ASSIGNEE>`       |       | Who owns it.                                 |
| `--due <DUE>`                 |       | A due date, free-form or ISO.                |
| `--project <PROJECT>`         | `-p`  | Reassign to another project.                 |
| `--milestone <MILESTONE>`     | `-m`  | Reassign to another milestone.               |

Reassigning rewrites only the edge you named. Moving a task to a different milestone leaves its project edge alone.

### base task done

Mark a task completed.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task done write-reference-setup-mdx
```

The short way to do what `base task update <slug> --status completed` does.

### base task tag

Attach or detach free-form labels.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task tag write-reference-setup-mdx --add docs
base task tag write-reference-setup-mdx --add docs --add reference
base task tag write-reference-setup-mdx --remove blocked
```

| Flag                | What it does                                                     |
| ------------------- | ---------------------------------------------------------------- |
| `--add <ADD>`       | A label to attach. Repeatable, and adding one twice is harmless. |
| `--remove <REMOVE>` | A label to detach. Repeatable.                                   |

### base task delete

**Destructive. Preview by default.** Delete a task and its edges.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base task delete write-reference-setup-mdx
base task delete write-reference-setup-mdx --yes
```

| Flag    | What it does                                                           |
| ------- | ---------------------------------------------------------------------- |
| `--yes` | Apply the delete. Without it, the task is printed and nothing changes. |

## Goals

A goal is a named target that is not a project and has no tasks under it.

### base goal add

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base goal add --name "Docs cover every shipped command" --target "120 command paths"
```

| Flag                | What it does                          |
| ------------------- | ------------------------------------- |
| `--name <NAME>`     | The goal. Required.                   |
| `--target <TARGET>` | What hitting it looks like. Required. |

### base goal list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base goal list
```

### base goal update

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base goal update docs-cover-every-shipped-command --status active
base goal update docs-cover-every-shipped-command --target "120 command paths, all green"
```

| Flag                | What it does       |
| ------------------- | ------------------ |
| `--status <STATUS>` | The goal's status. |
| `--target <TARGET>` | A revised target.  |

## Reminders

A reminder surfaces at the start of a session once its time has come, and keeps surfacing until you remove it.

### base reminder add

Give exactly one of `--in`, `--at` or `--due`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base reminder add --name "Check the Mintlify preview plan" --in 2h
base reminder add --name "Check the Mintlify preview plan" --due 2026-08-27
base reminder add --name "Check the Mintlify preview plan" --at 2026-08-27T09:30:00-05:00
```

| Flag            | What it does                                         |
| --------------- | ---------------------------------------------------- |
| `--name <NAME>` | What to be reminded of. Required.                    |
| `--due <DUE>`   | A date, `YYYY-MM-DD`. Surfaces on or after that day. |
| `--at <AT>`     | An exact time, ISO-8601 with an offset.              |
| `--in <IN_DUR>` | Relative to now: `30s`, `3m`, `2h`, `1d`.            |

### base reminder list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base reminder list
```

### base reminder remove

**Destructive, no preview.** Remove a reminder outright.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base reminder remove check-the-mintlify-preview-plan
```

This is a hard delete with no confirmation. Run `base reminder list` first to get the slug you actually mean.

## Entities

An entity is a person or an organization. Every entity must link to at least one domain, which is what stops orphans accumulating.

### base entity add

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base entity add --name "Mintlify" --entity-type organization --domain basemode
base entity add --name "Chris" --domain basemode --project basemode-docs
```

| Flag                   | What it does                                      |
| ---------------------- | ------------------------------------------------- |
| `--name <NAME>`        | The entity's name. Required.                      |
| `--entity-type <type>` | `person` or `organization`. Defaults to `person`. |
| `--domain <DOMAIN>`    | The domain this entity relates to. Required.      |
| `--project <PROJECT>`  | A project to link it to as well.                  |

### base entity list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base entity list
```

### base entity get

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base entity get mintlify
```

Accepts the slug or the display name.

### base entity update

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base entity update mintlify --status active
base entity update mintlify --description "Hosts docs.basemode.ai"
```

| Flag                          | What it does         |
| ----------------------------- | -------------------- |
| `--status <STATUS>`           | The entity's status. |
| `--description <DESCRIPTION>` | What it is.          |

## base reconcile

Read each project's folder for when it was last touched, and bring its active or deferred state back in line with that.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base reconcile --dry-run
base reconcile
```

| Flag        | What it does                                                                                         |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `--dry-run` | Show what would change and write nothing. Runs whether or not the protocol configuration is enabled. |

Run `--dry-run` first. This decides state from filesystem activity, so a project you have been working on outside its registered folder can look dormant when it is not.