DocsCLIco init

co init

Add ConnectOnion to an existing folder safely. Preserves your code and .env, appends only what's missing, refreshes docs to the latest version.

Download

Quick Start: cd existing-project && co init — your existing files stay put, ConnectOnion slots in around them.

init vs create

Use co create for a fresh project in a new directory. Use co init when you already have a folder — Django app, scripts, or an existing ConnectOnion project you want to refresh.

Feature	co create	co init
Creates new directory	Yes	No (uses current)
Works in non-empty dir	No	Yes
Uses global identity (~/.co/)	Yes	Yes
Handles existing .env	Creates fresh	Appends missing keys
Refresh docs anytime	On creation	Every run / --update-docs

Basic Usage

Drop into any directory and run co init:

code

bash

cd my-existing-project
co init

output

🧅 ConnectOnion Project Initializer

========================================

✓ Using global identity from ~/.co/

✓ Found existing .env file

✓ Appending API keys from ~/.co/keys.env

✓ Wrote .co/host.yaml

✓ Refreshed .co/docs/

✅ ConnectOnion project initialized!

Common one-liners:

Terminalbash

$co init

$co init -y

$co init -t minimal

$co init -t playwright

$co init --update-docs

What Gets Added

co init adds a small set of files. Everything else in your project stays exactly as it was.

Files created:

your-project//

├──🐍agent.py# added if missing — never overwritten

├──.env# created or appended with missing API keys

├──.co//

├──host.yaml# project config — uses global identity

└──docs//# always refreshed to latest

├──connectonion.md

└──co-vibe-coding-all-in-one.md

└──.gitignore# ConnectOnion entries appended

Identity (address + email) lives in ~/.co/keys.env and ~/.co/host.yaml — shared across every project. The per-project .co/host.yaml only stores project-specific overrides.

File Safety

Each file has a clear, predictable behavior. Your code is never touched.

File / Directory	If Exists	Behavior
agent.py	Skip	Won't overwrite your code
.env	Append	Adds only API keys that are missing
.co/docs/	Overwrite	Always pinned to latest framework docs
.co/host.yaml	Update	Merges, preserves custom keys
.gitignore	Append	Adds ConnectOnion entries if missing

How .env Is Merged

Global API keys live in ~/.co/keys.env. co init reads them and intelligently merges into your project's .env — four cases, all safe.

Case 1 — No .env File

Creates a fresh .env with your global keys.

code

bash

co init

output

# .env (created)

OPENAI_API_KEY=sk-proj-xxx

ANTHROPIC_API_KEY=sk-ant-xxx

GEMINI_API_KEY=AIza...

Case 2 — .env Exists, No API Keys

Appends the API keys section. Your variables stay intact.

code
bash
# Original .env
DATABASE_URL=postgres://localhost/mydb
SECRET_KEY=mysecret
output
# After co init
DATABASE_URL=postgres://localhost/mydb
SECRET_KEY=mysecret
 
# ConnectOnion API Keys
OPENAI_API_KEY=sk-proj-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

Case 3 — .env Has Some API Keys

Existing keys are preserved. Only the missing ones are added.

code
bash
# Original .env
OPENAI_API_KEY=sk-proj-old
output
# After co init
OPENAI_API_KEY=sk-proj-old   # untouched
 
# ConnectOnion API Keys
ANTHROPIC_API_KEY=sk-ant-xxx
GEMINI_API_KEY=AIza...

Case 4 — .env Has All Keys

Nothing to do — file isn't modified.

code

bash

co init

output

✓ .env already contains all API keys

Provider mapping

When you pass --key, the provider is auto-detected from the prefix:

• OpenAI → OPENAI_API_KEY
• Anthropic → ANTHROPIC_API_KEY
• Google → GEMINI_API_KEY
• Groq → GROQ_API_KEY

Templates

Same templates as co create — pick the closest fit, you can always edit afterward.

minimal

Basic agent with simple tools. Good starting point.

playwright

Browser automation — clicking, scraping, screenshots.

custom

Describe what you want — generated by AI.

code

bash

co init -t minimal
co init -t playwright
co init -t custom --description "Monitor a site and alert me on changes"

Refreshing Docs

The .co/docs/ folder ships with the framework — it's overwritten on every co init so the agent always has the current docs in context.

For a docs-only refresh in an existing project, use --update-docs:

code

bash

co init --update-docs

output

✓ Project already initialized

✓ Updated .co/docs/ to latest version

✅ Documentation updated!

Don't edit framework docs. They'll be overwritten on the next update. Put your own project rules in .co/OO.md instead — that file is yours, never touched by init.

Special Directory Warnings

co init refuses (or warns) when run in directories that probably aren't projects:

• Home directory (~)
• Root directory (/)
• System directories (/usr, /etc)
• Existing git repositories — warns, then continues

If you really mean it, pass --force:

code

bash

co init --force

Command Reference

Option	Short	Description
--template	-t	`minimal` \| `playwright` \| `custom`
--key	—	Paste an API key — provider auto-detected, appended to .env
--force	—	Continue in non-empty or special directories
--yes	-y	Accept defaults, skip prompts
--update-docs	—	Refresh `.co/docs/` only — leaves everything else alone
--no-ai	—	Disable AI features (not recommended)

Common Workflows

Add agents to a Django app

code

bash

cd my-django-app
co init

output

✓ Found existing .env file

✓ Appending API keys (DATABASE_URL preserved)

✓ Skipped agent.py (none found — created)

✓ Refreshed .co/docs/

✅ ConnectOnion project initialized!

Refresh an older ConnectOnion project

code

bash

cd old-agent-project
co init

output

✓ Project already initialized

✓ Adding ANTHROPIC_API_KEY (was missing)

✓ Refreshed .co/docs/ to latest

✅ Project updated!

Convert a scripts folder into an agent project

code

bash

cd my-scripts
co init -y

output

✓ Created .env with API keys

✓ Added agent.py template

✓ Your scripts untouched

✅ Ready — run: python agent.py

Troubleshooting

My .env had a different OPENAI_API_KEY — was it overwritten?

No. co init never replaces an existing key. Your old value stays. To use the global one, delete the line and re-run co init.

The docs in .co/docs/ look out of date

Run co init --update-docs. The folder is always overwritten with the latest framework docs.

I want a clean .env from scratch

Remove it manually, then re-init: rm .env && co init.

Refused to run — "special directory"

You're probably in ~, /, or a system path. Move into a project folder, or pass --force if you really mean it.

Best Practices

Review .env after init — confirm the API keys appended cleanly.

Refresh docs periodically — co init --update-docs keeps the agent's context fresh.

Commit .co/host.yaml — track project-specific config in git.

Never commit .env — keep API keys out of the repo.

Don't edit .co/docs/ — it's framework-owned, overwritten on update. Put your rules in .co/OO.md.

co init

init vs create

Basic Usage

What Gets Added

Files created:

File Safety

How .env Is Merged

Case 1 — No .env File

Case 2 — .env Exists, No API Keys

Case 3 — .env Has Some API Keys

Case 4 — .env Has All Keys

Provider mapping

Templates

minimal

playwright

custom

Refreshing Docs

Special Directory Warnings

Command Reference

Common Workflows

Add agents to a Django app

Refresh an older ConnectOnion project

Convert a scripts folder into an agent project

Troubleshooting

My .env had a different OPENAI_API_KEY — was it overwritten?

The docs in .co/docs/ look out of date

I want a clean .env from scratch

Refused to run — "special directory"

Best Practices

Star us on GitHub