one add

one add selects a technology stack, writes a locally developable project into the workspace, registers it in the manifest, and refreshes agent docs. CI and deployment remain unconfigured by default.

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.

Usage

one add [template-id] --name <project-name> [--deploy-provider <backend>] [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
`--deploy-provider <backend>`	Explicit deploy backend; must be in the template's compat list
`-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

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",
  "ai_guides": {
    "status": "completed",
    "providers": ["codex", "claude-code"],
    "generated_files": [
      "AGENTS.md",
      "CLAUDE.md",
      ".one/agents/conventions.md",
      ".one/agents/projects/services-user-api.md",
      ".one/agents/ops/dev.md",
      ".one/agents/ops/secrets.md",
      ".one/agents/ops/container.md",
      ".one/agents/ops/deploy.md"
    ],
    "file_count": 8
  }
}

warnings[] means a compatibility or post-sync step produced a non-blocking warning; the project was still added. ai_guides.status tells you whether root AGENTS.md, CLAUDE.md, and .one/agents/** refreshed successfully. ai_guides.generated_files contains workspace-relative paths.

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
Leaves deployment and image configuration absent until first deploy
Refreshes AGENTS.md, CLAUDE.md, and .one/agents/**

If a non-critical step fails, such as agent-doc refresh, the project still exists and the related status is marked failed or skipped.

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
`AI_GUIDE_EXISTS`	Root `AGENTS.md` / `CLAUDE.md` is user-managed and cannot be overwritten

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 <project> next; choose deployment later with one deploy <project>
Optionally run one ci enable <project> to generate its GitHub Actions workflow
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