DocsCLI Reference

CLI Reference

Quickly scaffold and manage ConnectOnion agent projects with the CLI.

Download

Quick Reference

co create → New project

co init → Current directory

co auth → Managed keys (free credits)

co deploy → Deploy to cloud

co status → Check balance

co reset → Reset account

co doctor → Diagnose issues

co -b → Browser automation

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).

co auth

Authenticate for managed LLM keys with free credits included.

Basic Usage

Terminal

$co auth

What It Does

1Signs message with your Ed25519 key
2Authenticates with OpenOnion backend
3Saves OPENONION_API_KEY to ~/.co/keys.env

Using Managed Keys

from connectonion import llm_do # Use co/ prefix for managed models response = llm_do("Hello", model="co/gpt-5") response = llm_do("Hello", model="co/claude-sonnet-4-5") response = llm_do("Hello", model="co/gemini-2.5-pro")

co status

Check your account balance and managed keys usage.

Terminal

$co status

Example Output

ConnectOnion Account Status
============================

Address:  0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a
Email:    0x7a9f3b2c@mail.openonion.ai
Balance:  $5.00

co reset

⚠️ Destructive: Reset your account and create a new identity.

Terminal

$co reset

What It Does

Deletes your account data
Clears balance and usage history
Creates new account with new keys
Generates new address and email

Example Output

$ co reset

⚠️  WARNING: This will delete ALL your data
Including:
  - Account balance
  - Usage history
  - Current identity

Continue? (y/N): y

✓ Account reset
✓ New identity created
✓ New address: 0x9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0

When to use: Starting completely fresh, testing account creation, or removing old identity.

co deploy

Deploy your agent to ConnectOnion Cloud.

Terminal

$co deploy

Requirements

Git repository with committed code
.co/config.toml (created by co create or co init)
Authenticated (co auth)

Example Output

$ co deploy

Deploying to ConnectOnion Cloud...

  Project: my-agent
  Secrets: 3 keys

Uploading...
Building...

Deployed!
Agent URL: https://my-agent-abc123.agents.openonion.ai

Beta: This feature is in beta. See the Deploy Guide for more details.

co doctor

Comprehensive diagnostics for your ConnectOnion installation.

Terminal

$co doctor

What It Checks

System

• Version
• Python
• Environment

Configuration

• Config files
• Keys
• API keys

Connectivity

• Backend
• Authentication
• Network

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

Connect to Agents

Tutorial: AI Agent = Prompt + Function