Manual workspace

This tutorial covers exactly one command: one create. Picking which templates to use is the previous chapter; deploying for the first time is the next chapter.

1. Install the CLI

curl -fsSL https://1cli.dev/install.sh | bash
one --version

Manual options live in installation.

2. Run one create

The simplest form prompts you interactively for everything:

one create my-workspace

If you came from the templates page with a generated command, you can paste it directly — it has --add / --env-provider already filled in.

Non-interactive form (for scripts and CI):

one create my-workspace \
  --yes \
  --env-provider dotenv

Key flags:

Flag	What it does
--name <name>	Workspace name (overrides positional arg's basename)
--yes	Skip all prompts; accept defaults
--env-provider dotenv | infisical	Choose the env backend (default: dotenv; switch later with one env switch infisical)
--add <template-id>[:<project-name>]	Pre-add a project; repeatable

For the full list, see the one create reference.

3. What got written

cd my-workspace
ls -la

You'll see something like:

.git/
.github/
apps/
one.manifest.json
packages/
services/

Inspect the manifest:

cat one.manifest.json | jq

Key parts of the produced manifest:

• version: 1 — required schema version
• workspace.id — generated UUID
• environments.names: ["dev", "preview", "prod"] and default: "dev"
• domains.env — the env backend you chose (dotenv or infisical)
• domains.deploy and domains.container — left unset at this stage; filled in when individual projects opt into deploy / container backends
• projects: [] — empty unless you passed --add

4. Defaults wired by one create

Every new workspace gets two baseline capabilities without prompting:

Domain	Backend	What it gives you
env	dotenv (or infisical if you chose it)	.env file management for every project
dev	process	Each one add records a dev command at projects[].domains.dev.command, run by one dev via the built-in supervisor

CI is not configured by one create or one add, and no workflow file is generated automatically.

5. The first commit

git status
git add .
git commit -m "chore: scaffold workspace"

one create already ran git init. The first commit captures the skeleton.

Common errors

Code	Symptom	Fix
INVALID_NAME	Workspace name has unsupported characters	Use ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ (kebab-case is safe)
WORKSPACE_NESTED_FORBIDDEN	Tried to one create inside an existing workspace	Run from a non-workspace directory
TARGET_EXISTS	The target directory already exists and is non-empty	Pick a different name, or empty the directory first
TEMPLATE_NOT_FOUND	--add <id> used an unknown template id	Run one templates list or visit the templates page

Full table: error codes.

Next

• Set your first env var → Configure env vars