ConnectOnion Init Command

co init sets up global credentials. Project initialization requires an explicit directory, such as co init ./.

Quick start

co init --yes                     # ~/.co/keys.env and the global identity
co init ./ --yes                  # configuration in this existing project
co init /path/to/project --yes    # configuration in another existing project
co init ./ --template co-ai       # also add the hosted agent template

The path must name an existing directory. Use co create my-agent to create a new directory with the default co-ai template.

Global setup: no path

Plain co init creates or reuses the signing identity in ~/.co/keys/ and attempts managed-key authentication, saving credentials to ~/.co/keys.env. It does not create or modify the current directory's .env, .co/, agent.py, or other project files—even when run inside an existing project.

Existing global provider credentials are preserved. An explicit --key saves that provider key globally; keys merely present in the process environment or loaded from a project are not copied into global storage. Avoid putting secrets into shell history; editing the private keys file is also supported.

If authentication cannot complete, local identity setup remains available and the command tells you to run co auth later. Successful local initialization does not mean managed models or email are authenticated.

Project setup: explicit path

co init ./ uses the global identity and initializes the selected directory. It does not mint a separate project keypair.

File	Behavior
.env	Create or append missing credentials; preserve existing provider and application values
Identity entries in .env	Refresh from global identity, including after co reset
CO_INVITE_CODE	Create once per project; preserve on subsequent runs
.co/host.yaml	Create project configuration if missing
.co/docs/	Refresh bundled framework documentation
.co/admins.txt	Record the creating identity as an admin
Template files such as agent.py	Only with --template; preserve existing files unless --force
.gitignore	Add secret/runtime exclusions when initializing inside a Git repository

Personal Google/Microsoft OAuth credentials and machine-specific configuration paths are not copied from global keys into a project. Keep both .env and keys.env out of source control.

# Add configuration without generating agent.py
co init ./ --yes

# Add the hosted template
co init ./ --template co-ai --yes

# Generate a custom agent
co init ./ --template custom --description "Monitor a site and alert me"

# Refresh configuration and bundled docs without selecting a code template
co init ./ --yes

Non-empty and special directories prompt for confirmation unless --yes is given. --yes does not authorize overwriting existing template code; --force does. Treat refreshed .co/docs/ as generated framework reference, not a place for personal notes.

Options

Option	Meaning
PATH	Optional existing project directory; omission selects global setup
--key	Explicit provider key: global storage without PATH, project configuration with PATH
--yes, -y	Skip project confirmation prompts
--template, -t	Project only: co-ai or custom; omitted means configuration only
--description	Project only: description for a custom template
--force	Project only: allow replacing existing template files

Project-only options without PATH fail before writing files and show an example using co init ./.

Migrating scripts

Commands that formerly relied on implicit project initialization must add a path:

# Before: co init --yes --template co-ai
co init ./ --yes --template co-ai

Global setup scripts can keep co init --yes. co create is unchanged. At runtime, explicit process variables take precedence over the selected env file, which is global ~/.co/keys.env unless co --env-file PATH names a project file; there is no per-key fallback between files. co env shows what the selected file holds and co env set edits it. See CLI reference for authentication and credential diagnostics.