CLI
CLI
Generated command reference for the Project CLI.
Documentation track: current
mainsource. This reference can be ahead of the latest published binary. Checkproject --versionand the latest GitHub release before assuming a command is installed.
Flag details cover managed macOS, Linux, and WSL installations. The native Windows CLI delegates runtime commands to WSL and can expose a smaller guidance-only flag surface.
This page is generated from the same Cobra command tree used by the project binary.
Base Command
project| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for project |
-v, --version | bool | local | version for project |
Commands
| Command | Aliases | Description |
|---|---|---|
adopt | - | Plan adoption of an existing project |
approval | - | Manage cryptographic human approvals |
chat | - | Coordinate with people and agents through Project Chat |
codex | - | Start, inspect, continue, or attach to persistent Codex tasks |
completion | - | Generate the autocompletion script for the specified shell |
connect | - | Connect this machine to Project Space |
connector | - | Set up Project Space machine connector links |
create | new | Create and initialize a new project |
deploy | - | Deploy this project to the VPS |
disconnect | - | Disconnect this machine from Project Space |
doctor | - | Check this machine's Project Space connection |
help | - | Help about any command |
init | - | Initialize a project template lock |
module | - | Manage project template modules |
prepare | - | Run trusted repository setup steps |
run | - | Run a configured project script in the foreground |
self-update | - | Check for and install a signed Project CLI release |
serve | - | Run a project script and expose it on this Tailnet |
status | - | Show this machine's Project Space connection |
template | - | Manage the local project template snapshot |
token | - | Manage the Project 1Password token |
validate | - | Validate a project against its template |
worktree | - | Prepare and validate isolated Codex worktrees |
Command Reference
project adopt
Plan adoption of an existing project
project adopt [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show the adoption plan without writing changes |
--format | string | local | output format |
-h, --help | bool | local | help for adopt |
--module | string | local | adopt a template module by adding only missing files |
--reason | string | local | reason for a waiver |
--waive | string | local | add a waiver for a path pattern |
-y, --yes | bool | local | apply the adoption action without prompting |
project approval
Manage cryptographic human approvals
project approval| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for approval |
project approval enroll
Create an external trusted signer configuration with macOS authentication
project approval enroll| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for enroll |
--policy | string | local | repository approval policy |
--root | string | local | repository root |
--trust-root | string | local | external trusted signer configuration |
project approval sign
Approve one scope using Secure Enclave authentication
project approval sign| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for sign |
--policy | string | local | repository approval policy |
--root | string | local | repository root |
--scope | string | local | scope identifier to approve |
--trust-root | string | local | external trusted signer configuration |
project approval status
Show approval state
project approval status| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for status |
--policy | string | local | repository approval policy |
--root | string | local | repository root |
--trust-root | string | local | external trusted signer configuration |
project approval verify
Verify every required human approval
project approval verify| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for verify |
--policy | string | local | repository approval policy |
--root | string | local | repository root |
--trust-root | string | local | external trusted signer configuration |
project chat
Coordinate with people and agents through Project Chat
project chat| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for chat |
project chat claim
Claim an available registry name for this Codex thread
project chat claim <registry-name>| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for claim |
--parent-thread | string | local | main-agent thread ID (required for specialist names) |
project chat names
List Project Chat registry names and availability
project chat names| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for names |
project chat read
Read unread messages from #general
project chat read| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for read |
project chat send
Send one message to #general
project chat send <message>| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for send |
project codex
Start, inspect, continue, or attach to persistent Codex tasks
project codex| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for codex |
project codex attach
Attach the Codex TUI to an existing persistent thread
project codex attach| Flag | Type | Scope | Description |
|---|---|---|---|
--codex-binary | string | local | explicit Codex CLI binary path |
--connector | string | local | exact connector installation ID |
-h, --help | bool | local | help for attach |
--machine | string | local | exact physical machine name |
--machine-id | string | local | exact physical machine ID |
--operation-id | string | local | stable idempotency key for safe retries |
--thread | string | local | persistent Codex thread ID |
project codex read
Read a persistent Codex thread non-interactively
project codex read| Flag | Type | Scope | Description |
|---|---|---|---|
--connector | string | local | exact connector installation ID |
--format | string | local | output format: json |
-h, --help | bool | local | help for read |
--last | int | local | return only the last N turns |
--machine | string | local | exact physical machine name |
--machine-id | string | local | exact physical machine ID |
--thread | string | local | persistent Codex thread ID |
project codex send
Send a non-interactive turn to a persistent Codex thread
project codex send| Flag | Type | Scope | Description |
|---|---|---|---|
--connector | string | local | exact connector installation ID |
--format | string | local | output format: json or ndjson |
-h, --help | bool | local | help for send |
--machine | string | local | exact physical machine name |
--machine-id | string | local | exact physical machine ID |
--message | string | local | turn prompt, or - to read from standard input |
--no-wait | bool | local | return as soon as the turn is accepted |
--operation-id | string | local | stable idempotency key for safe retries |
--prompt-file | string | local | read the turn prompt from a regular file |
--thread | string | local | persistent Codex thread ID |
--wait | bool | local | wait for the turn to complete or require interaction |
project codex start
Start a persistent Codex task from a GitHub issue
project codex start| Flag | Type | Scope | Description |
|---|---|---|---|
--connector | string | local | exact connector installation ID |
--dry-run | bool | local | resolve the exact target without starting a task |
--format | string | local | output format: text or json |
-h, --help | bool | local | help for start |
--here | bool | local | use the physical machine connected by this CLI |
--issue | int | local | GitHub issue number |
--machine | string | local | exact physical machine name |
--machine-id | string | local | exact physical machine ID |
--operation-id | string | local | stable idempotency key for safe retries |
--repository | string | local | exact GitHub owner/name or repository ID |
project completion
Generate the autocompletion script for the specified shell
project completion| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for completion |
project completion bash
Generate the autocompletion script for bash
project completion bash| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for bash |
--no-descriptions | bool | local | disable completion descriptions |
project completion fish
Generate the autocompletion script for fish
project completion fish| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for fish |
--no-descriptions | bool | local | disable completion descriptions |
project completion powershell
Generate the autocompletion script for powershell
project completion powershell| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for powershell |
--no-descriptions | bool | local | disable completion descriptions |
project completion zsh
Generate the autocompletion script for zsh
project completion zsh| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for zsh |
--no-descriptions | bool | local | disable completion descriptions |
project connect
Connect this machine to Project Space
project connect| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for connect |
--json | bool | local | print machine-readable output |
--name | string | local | machine name shown in Project Space |
--no-open | bool | local | print the approval URL without opening a browser |
project connector
Set up Project Space machine connector links
project connector| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for connector |
project connector connect
Add or update one Project Space connector hub
project connector connect <name> <url>| Flag | Type | Scope | Description |
|---|---|---|---|
--config | string | local | connector config file path |
--disabled | bool | local | write the hub but keep it disabled |
-h, --help | bool | local | help for connect |
--json | bool | local | print machine-readable output |
--token-env | string | local | environment variable that contains the connector registration token |
project connector install
Install and start the machine connector service
project connector install| Flag | Type | Scope | Description |
|---|---|---|---|
--binary | string | local | connector binary to install |
--config | string | local | connector config file path |
--dev-url | string | local | local development Project Space hub URL |
-h, --help | bool | local | help for install |
--install-dir | string | local | directory for the installed connector |
--json | bool | local | print machine-readable output |
--no-dev | bool | local | only configure the remote Project Space hub |
--prod-url | string | local | remote Project Space hub URL |
--service-name | string | local | connector service name shown in Project Space |
--token-env | string | local | environment variable that contains the connector registration token |
--token-file | string | local | private file used by the service to load the registration token |
project connector run
Run the authenticated Project Space connector
project connector run| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for run |
project connector setup
Configure this machine connector for prod and local Project Space hubs
project connector setup| Flag | Type | Scope | Description |
|---|---|---|---|
--config | string | local | connector config file path |
--dev-url | string | local | local development Project Space hub URL |
-h, --help | bool | local | help for setup |
--json | bool | local | print machine-readable output |
--no-dev | bool | local | only configure the remote Project Space hub |
--prod-url | string | local | remote Project Space hub URL |
--token-env | string | local | environment variable that contains the connector registration token |
project connector source
Run an isolated development connector from source
project connector source| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for source |
project connector source connect
Pair the isolated source development connector
project connector source connect| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for connect |
--json | bool | local | print machine-readable output |
--name | string | local | display name shown in Project Space |
--no-open | bool | local | print the approval URL without opening a browser |
--root | string | local | trusted Project Space source checkout |
project connector source run
Run the paired development connector from source
project connector source run| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for run |
--root | string | local | trusted Project Space source checkout |
project connector source status
Show the isolated development connector status
project connector source status| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for status |
--json | bool | local | print machine-readable output |
project connector status
Show configured Project Space connector hubs
project connector status| Flag | Type | Scope | Description |
|---|---|---|---|
--config | string | local | connector config file path |
-h, --help | bool | local | help for status |
--json | bool | local | print machine-readable output |
project create
Create and initialize a new project
project create [directory]Aliases: new
| Flag | Type | Scope | Description |
|---|---|---|---|
--commit | string | local | template commit or label |
--force | bool | local | replace an existing .project/template.lock.yaml |
--github | bool | local | create a private GitHub repository and push the project |
--github-visibility | string | local | GitHub repository visibility |
--global-tmp | bool | local | create a global tmp project in /tmp and install default modules |
-h, --help | bool | local | help for create |
--local-tmp | bool | local | create a local tmp project in ./tmp and install default modules |
--template | string | local | template repository |
--template-path | string | local | template path |
--tmp | bool | local | create a local tmp project in ./tmp and install default modules |
--version | string | local | template version |
project deploy
Deploy this project to the VPS
project deploy [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--api-domain | string | local | project API domain |
--branch | string | local | git branch to deploy |
--commit | string | local | full Git commit SHA to deploy |
--domain | string | local | project domain |
--dry-run | bool | local | print planned remote actions without changing the VPS |
--email | string | local | Traefik ACME email |
--env | string | local | deployment environment: prod or beta |
--format | string | local | output format |
-h, --help | bool | local | help for deploy |
--host | string | local | SSH host |
--lock-timeout | duration | local | maximum time to wait for the remote deployment lock |
--path | string | local | remote project directory |
project deploy status
Inspect deployment status without changing the VPS
project deploy status [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--all-envs | bool | local | inspect all configured environments |
--api-domain | string | local | project API domain |
--branch | string | local | git branch to deploy |
--commit | string | local | full Git commit SHA to deploy |
--domain | string | local | project domain |
--email | string | local | Traefik ACME email |
--env | string | local | deployment environment: prod or beta |
--format | string | local | output format |
-h, --help | bool | local | help for status |
--host | string | local | SSH host |
--lock-timeout | duration | local | maximum time to wait for the remote deployment lock |
--path | string | local | remote project directory |
project disconnect
Disconnect this machine from Project Space
project disconnect| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for disconnect |
--json | bool | local | print machine-readable output |
project doctor
Check this machine's Project Space connection
project doctor| Flag | Type | Scope | Description |
|---|---|---|---|
--fix | bool | local | create missing project directories |
-h, --help | bool | local | help for doctor |
--json | bool | local | print machine-readable output |
project help
Help about any command
project help [command]| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for help |
project init
Initialize a project template lock
project init [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--commit | string | local | template commit or label |
--force | bool | local | replace an existing .project/template.lock.yaml |
-h, --help | bool | local | help for init |
--template | string | local | template repository |
--template-path | string | local | template path |
--version | string | local | template version |
project module
Manage project template modules
project module| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for module |
project module add
Add a project template module
project module add <module> [directory]Aliases: install
| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show the module add plan without writing changes |
--force | bool | local | allow module add to overwrite existing project files |
--format | string | local | output format |
-h, --help | bool | local | help for add |
-y, --yes | bool | local | apply the module add plan without prompting |
project module list
List project template modules
project module list [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format |
-h, --help | bool | local | help for list |
project module remove
Remove a project template module
project module remove <module> [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show the module remove plan without writing changes |
--format | string | local | output format |
-h, --help | bool | local | help for remove |
-y, --yes | bool | local | apply the module remove plan without prompting |
project module show
Show details for a project template module
project module show <module> [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format |
-h, --help | bool | local | help for show |
project prepare
Run trusted repository setup steps
project prepare [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--expect-commit | string | local | require this exact repository commit before setup |
--expect-declaration-digest | string | local | require this exact setup declaration digest before setup |
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for prepare |
--json | bool | local | print machine-readable JSON output |
--step | string | local | stable setup step ID (default: all steps in declaration order) |
project prepare status
Inspect trusted repository setup
project prepare status [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--expect-commit | string | local | require this exact repository commit before setup |
--expect-declaration-digest | string | local | require this exact setup declaration digest before setup |
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for status |
--json | bool | local | print machine-readable JSON output |
--step | string | local | stable setup step ID (default: all steps in declaration order) |
project run
Run a configured project script in the foreground
project run <script> [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for run |
--json | bool | local | print machine-readable JSON output |
project self-update
Check for and install a signed Project CLI release
project self-update| Flag | Type | Scope | Description |
|---|---|---|---|
--check | bool | local | check the signed approved release without changing files |
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for self-update |
-y, --yes | bool | local | install the verified update without prompting |
project serve
Run a project script and expose it on this Tailnet
project serve [script] [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--allowed-host | stringArray | local | explicit Vite host allowed to reach this session (repeatable) |
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for serve |
--json | bool | local | print machine-readable JSON output |
project serve list
List trusted development servers configured by a repository
project serve list [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for list |
--json | bool | local | print machine-readable JSON output |
project serve reconcile
Check managed project servers and clean stale sessions
project serve reconcile| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for reconcile |
--json | bool | local | print machine-readable JSON output |
project serve status
Inspect a managed project server
project serve status [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for status |
--json | bool | local | print machine-readable JSON output |
--script | string | local | configured script name |
project serve stop
Stop one managed project server
project serve stop [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: pretty or json |
-h, --help | bool | local | help for stop |
--json | bool | local | print machine-readable JSON output |
--script | string | local | configured script name |
project status
Show this machine's Project Space connection
project status| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for status |
--json | bool | local | print machine-readable output |
project template
Manage the local project template snapshot
project template| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for template |
project template lint
Validate a template checkout
project template lint| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format |
-h, --help | bool | local | help for lint |
--template-path | string | local | template checkout path |
project template smoke
Generate a tmp project and run template smoke checks
project template smoke| Flag | Type | Scope | Description |
|---|---|---|---|
--commit | string | local | template commit or label |
--container | bool | local | build generated project containers |
--global-tmp | bool | local | create the generated project under /tmp |
-h, --help | bool | local | help for smoke |
--name | string | local | tmp project name prefix |
--skip-checks | bool | local | skip dependency, secrets, check, and build commands |
--skip-secrets-doctor | bool | local | skip bun run secrets:doctor |
--template | string | local | template repository |
--template-path | string | local | template path |
--version | string | local | template version |
project template sync
Sync the local template snapshot
project template sync [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show the template sync plan without writing changes |
--format | string | local | output format |
-h, --help | bool | local | help for sync |
--template-path | string | local | template source path |
project template update
Update a project from its template
project template update [directory]| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show the template update plan without writing changes |
--format | string | local | output format |
-h, --help | bool | local | help for update |
--template-path | string | local | template source path |
-y, --yes | bool | local | apply the template update without prompting |
project token
Manage the Project 1Password token
project token| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for token |
project token create
Create the Project 1Password service account token
project token create| Flag | Type | Scope | Description |
|---|---|---|---|
--dry-run | bool | local | show what would happen without creating a token |
--expires-in | string | local | create a temporary token with a 1Password expiry, for example 24h |
-h, --help | bool | local | help for create |
--json | bool | local | print machine-readable output |
-y, --yes | bool | local | create the token without prompting |
project validate
Validate a project against its template
project validate [directory|file]| Flag | Type | Scope | Description |
|---|---|---|---|
--color-scope | string | local | color scope |
--dry-run | bool | local | show the quarantine plan without writing changes |
--format | string | local | output format |
-h, --help | bool | local | help for validate |
--quarantine | bool | local | move not_allowed validation violations into .project/quarantine |
--status-color-only | bool | local | color only the status text |
--view | string | local | pretty output view |
-y, --yes | bool | local | apply the quarantine plan without prompting |
project worktree
Prepare and validate isolated Codex worktrees
project worktree| Flag | Type | Scope | Description |
|---|---|---|---|
-h, --help | bool | local | help for worktree |
project worktree check
Validate that the current Codex thread owns this isolated worktree
project worktree check| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: text or json |
-h, --help | bool | local | help for check |
project worktree materialize
Materialize a server-approved GitHub branch in the Project-managed worktree root
project worktree materialize| Flag | Type | Scope | Description |
|---|---|---|---|
--branch | string | local | server-approved exact branch identity |
--commit | string | local | server-approved exact commit |
--format | string | local | output format: json |
-h, --help | bool | local | help for materialize |
--repository | string | local | server-approved GitHub owner/name |
project worktree prepare
Prepare the worktree owned by the current Codex thread
project worktree prepare [task-name]| Flag | Type | Scope | Description |
|---|---|---|---|
--format | string | local | output format: text or json |
-h, --help | bool | local | help for prepare |
--issue | int | local | prepare a worktree for an existing open GitHub issue |