one add

one add selects a technology stack, writes a locally developable project into the workspace, and registers it in the manifest. 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"
}

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:

1. Project kind: application / service / shared library
2. Technology stack, such as nestjs-api
3. 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

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 <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