one add

one add creates a project from a template or an empty directory starter and registers it in the workspace manifest. CI and deployment remain unconfigured by default.

When hk is enabled, one add updates the default language checks in .config/hk.pkl, preserving user edits and comments. Workspace and project tasks share the root mise.toml; project directories retain only their native command files. See hooks and tasks for configuration details.

There are two entry points:

Human first run: run one add and use the interactive picker to choose the category, template, and project name.
Scripted or known-template flow: run one templates to see template IDs, then run one add <template-id> --name <project-name>.

template-id is the template ID, such as nestjs-api, nextjs-app, or ts-library. It is not the project name; the project name comes from --name.

Creation and project addition prepare mise and automatically trust complete mise.toml files generated by One, so entering the new workspace does not require a separate trust command. Existing custom configuration keeps mise's trust policy. If no compatible runtime is installed, One may download its managed mise binary; project tools and dependencies are still installed when needed. A trust failure preserves the generated files and prints a recovery command.

Usage

one add [template-id] --name <project-name> [options]

Arguments

Argument	Description
`template-id`	Template ID, such as `nestjs-api`. Omit it for interactive selection
`-n, --name`	Project name; required in non-interactive mode
`-y, --yes`	Non-interactive mode
`-o, --output <fmt>`	`json` / `yaml` / `text`

The workspace root uses pnpm. Each project's toolchain comes from the template: Node templates use the workspace package manager, Go templates use the Go toolchain, and so on.

Interactive Mode

Running one add with no arguments asks, in order: what you want to add (application, service, or shared library), which technology stack to use, and the project name. These three groups match the generated directories: apps/, services/, and packages/. Documentation sites are applications and appear in the first group. It does not ask about deployment.

Non-interactive calls should pass both template ID and project name:

one add nestjs-api --name api --yes

Create an Empty Project

In an existing workspace, create and register a project before choosing a language or framework:

one add empty-app --name web --yes
one add empty-service --name api --yes
one add empty-library --name shared --yes

These templates create apps/web/, services/api/, and packages/shared/, respectively, containing only a .gitkeep file so Git tracks the directory. They register toolchain: "none" and generate no package.json, go.mod, dependencies, or startup tasks. Interactive one add and the Dashboard's new-project picker also offer these choices.

For Node or Go code, set the project's toolchain in one.manifest.json to node or go. Node projects use packageManager: "pnpm" and need membership in the root package workspace; Go modules need membership in the root go.work. Define tasks in package.json / Taskfile.yml, or set the project's dev.command, then run one init mise to update task configuration. For other languages, keep toolchain: "none" and define your own tools and tasks in the root mise.toml, or set dev.command. Configure the commands before using one dev / one build.

Output

{
  "schema": "one-cli/add/v1",
  "subproject_name": "user-api",
  "target_path": "/abs/path/my-app/services/user-api",
  "template_id": "nestjs-api",
  "toolchain": "node",
  "package_manager": "pnpm"
}

warnings[] means a compatibility or post-sync step produced a non-blocking warning; the project was still added.

Examples

Interactive

cd my-app
one add

This flow asks for:

Project kind: application / service / shared library
Technology stack, such as nestjs-api
Project name, such as api

Use this path when you are not sure which template ID to type.

List Templates, Then Add Explicitly

one templates
one add nestjs-api --name api

The id shown by one templates is the first argument after one add.

Non-interactive / CI / Agent

one add nestjs-api --name user-api --yes
one add nextjs-app --name web --yes
one add ts-library --name shared --yes

Agent JSON Call

one add nestjs-api --name user-api --yes -o json | jq

What Gets Synced

Registers the project in one.manifest.json#projects[]
Writes the project's local development command
Leaves continuous integration unconfigured

Non-blocking sync issues are reported in warnings[]; the project is still added.

Common Errors

Code	Recovery
`TEMPLATE_NOT_FOUND`	Template ID is wrong; read `available_templates` from error context and choose one
`TEMPLATE_REQUIRED`	No template ID was provided in a non-interactive context; pass one explicitly
`INVALID_NAME`	`--name` must match `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`
`SUBPROJECT_NAME_REQUIRED`	Non-interactive mode requires `--name`
`TARGET_EXISTS`	Project directory already exists; choose a different `--name`
`NOT_ONE_PROJECT`	cwd is not a workspace; run `one create <dir>` or `cd` into an existing workspace
`REGISTRY_FETCH_FAILED`	Network or registry issue; inspect the registry URL in context

Full table: Error codes.

Template Choice

Not sure which one to use? Read the template decision tree.

After Adding

Check one.manifest.json#projects[] to confirm registration
Agent docs and local-development configuration are synced by one add
Run one dev -p <project> for development and one build -p <project> to build
one add does not install dependencies: JS / TS workspaces install from the root with the package manager; Go projects run go mod download in the project directory, then go mod tidy only after changing imports or when module metadata needs repair