CLI Reference

Quickly scaffold and manage ConnectOnion agent projects with the CLI.

Quick Reference

co create → New project

co init → Current directory

co create --ai → With AI features

co -b "screenshot..." → Browser commands

Installation

The CLI is automatically installed when you install ConnectOnion:

Terminal

$pip install connectonion

This provides two equivalent commands: co (short form) and connectonion (full form)

Commands Overview

ConnectOnion provides two main commands for project creation:

co create [name]

Creates a new project directory with all necessary files

co init

Initializes the current directory as a ConnectOnion project

Both commands share the same interactive flow:

1AI feature toggle (Yes/No)
2API key input (with auto-detection)
3Template selection

co create [name]

Create a new ConnectOnion project in a new directory.

Basic Usage

Interactive mode (prompts for project name)

$co create

With project name (skips name prompt)

$co create my-agent

With all options (no interaction)

$co create my-agent --ai --key sk-proj-xxx --template minimal

Options

Option	Description
[name]	Optional project name (creates directory)
--ai/--no-ai	Enable or disable AI features
--key	API key for AI provider (auto-detects provider)
--template	Choose template: `minimal`,`web-research`,`custom`
--description	Description for custom template (requires AI)
--yes, -y	Skip all prompts, use defaults

Interactive Flow Example

Terminal Output

$ co create

✔ Project name: … my-agent
✔ Enable AI features? (Y/n) … Y
✔ Paste your API key (or Enter to skip): … sk-proj-abc123
  ✓ Detected OpenAI API key
✔ Choose a template:
  ❯ Minimal - Simple starting point
    Web Research - Data analysis & web scraping
    Custom - AI generates based on your needs

✅ Created 'my-agent' with Minimal template

Next steps:
  cd my-agent
  python agent.py

co init

Initialize a ConnectOnion project in the current directory.

Basic Usage

Initialize current directory interactively

$co init

Skip prompts with options

$co init --no-ai --template minimal

Note: Options are the same as co create, except no [name] parameter (uses current directory name).

Browser Features

Guide the browser to do something using natural language commands. Use -b (short for browser) or the full browser subcommand:

Tip: co -b is short for co browser. Both syntaxes work the same way!

Take a screenshot (using -b shorthand)

$co -b "screenshot example.com save to screenshot.png"

Same command using full syntax

$co browser "screenshot example.com save to screenshot.png"

Screenshot with device preset

$co -b "screenshot example.com save to mobile.png size iPhone"

Device Presets

iPhone

390×844

iPad

768×1024

Desktop

1920×1080 (default)

Templates

Minimal

Basic agent structure with essential components:

Simple agent.py with basic tools
Minimal dependencies
Quick start configuration

Web Research

Advanced template for data analysis and web scraping:

Web scraping tools
Data extraction utilities
Browser automation support
API integration examples

Custom (AI-only)

Only available when AI is enabled. Generates a complete custom template based on your description:

✔ Choose template: Custom
✔ Describe what you want to build: … 
  I need an agent that monitors GitHub repos and 
  sends notifications for new issues

Generating custom template with AI...
✅ Created custom GitHub monitoring agent

API Key Detection

The CLI automatically detects your API provider from the key format:

Provider	Key Format	Example
OpenAI	sk-... or sk-proj-...	sk-proj-abc123...
Anthropic	sk-ant-...	sk-ant-api03-xyz...
Google	AIza...	AIzaSyAbc123...
Groq	gsk_...	gsk_abc123...

The appropriate environment variables and model configurations are set automatically.

What Gets Created

Project Structure

Files created:

my-agent/

├──🐍agent.py# Main agent implementation

├──tools/# Custom tools directory

├──prompts/# System prompts (AI-enabled)

├──.env# Environment configuration

├──.co/# ConnectOnion metadata

├──config.toml# Project configuration

├──keys/# Agent cryptographic keys

├──agent.key# Private signing key

├──recovery.txt# 12-word recovery phrase

└──DO_NOT_SHARE# Security warning

└──docs/

└──co-vibecoding-principles-docs-contexts-all-in-one.md# Complete VibeCoding & framework docs

├──README.md# Project documentation

└──.gitignore# Git ignore rules

Agent Identity

Every project automatically gets:

Ed25519 cryptographic keys for agent identity
Unique address (hex-encoded public key)
12-word recovery phrase for key restoration

Keys are stored in .co/keys/ and auto-added to .gitignore

Examples

Minimal project without AI

$co create simple-bot --no-ai --template minimal

Web research project with AI

$co create research-agent --ai --template web-research

Custom AI agent with description

$co create slack-bot --ai --template custom --description "Slack bot that answers questions"

Initialize existing directory

$cd my-existing-project

$co init --ai --template minimal

Best Practices

Choose the Right Command

Use co create for new projects,co init for existing directories.

API Key Security

Never commit .env files. Store API keys securely.

Template Selection

Start with Minimal for learning. Use Custom (with AI) for specific needs.

Agent Keys

Never share .co/keys/ directory. Backup your recovery phrase.

Troubleshooting

Command Not Found

If co command is not found after installation:

Terminal

$# Use full command

$python -m connectonion.cli.main create

$# Or reinstall

$pip uninstall connectonion

$pip install connectonion

Python Version

ConnectOnion requires Python 3.8 or higher. Check your version:

Terminal

$python --version

API Key Issues

Check key format matches your provider
Ensure key is active and has credits
Try pasting without quotes or spaces

Vibe Coding Guide

System Prompts