CLICLI Reference
DocsCLI Reference

CLI Reference

Quickly scaffold and manage ConnectOnion agent projects with the CLI.

Command Reference
Daily Use
co aiAI coding agent in your terminalco browserScreenshots, scraping & automationco outlookSend and read Outlook emailco gmailSend and read your Gmailco gdriveList, download & upload Drive filesco emailYour agent's own email address
Project Setup
co create [name]Scaffold a new agent projectco initAdd ConnectOnion to current directoryco authGet managed keys + $5 free creditsco setupGlobal identity + skill library in ~/.co/

Installation

The CLI is automatically installed when you install ConnectOnion:

Terminalbash
$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:

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

co create [name]

Create a new ConnectOnion project in a new directory.

Basic Usage

Interactive mode (prompts for project name)bash
$co create
With project name (skips name prompt)bash
$co create my-agent
With all options (no interaction)bash
$co create my-agent --ai --key sk-proj-xxx --template co-ai

Options

OptionDescription
[name]Optional project name (creates directory)
--ai/--no-aiEnable or disable AI features
--keyAPI key for AI provider (auto-detects provider)
--templateChoose template: co-ai (default — the same agent co ai runs),custom
--descriptionDescription for custom template (requires AI)
--yes, -ySkip 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:
  ❯ 🚀 Agent - The co ai agent, hosted — specialise it with skills
    ✨ Custom - AI generates based on needs

✅ Created 'my-agent'

Next steps:
  cd my-agent
  python agent.py

co init

Initialize a ConnectOnion project in the current directory.

Basic Usage

Initialize current directory interactivelybash
$co init
Skip prompts with optionsbash
$co init --no-ai --template co-ai

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

Terminalbash
$co auth

What It Does

  1. 1Signs message with your Ed25519 key
  2. 2Authenticates with OpenOnion backend
  3. 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-4o") 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, managed keys usage, and deployed agents.

Terminalbash
$co status

Example Output

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

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

Deployed Agents
Project       Status    Active  Container  URL
co-ai-agent   running   yes     running    https://co-ai-agent-0x....agents.openonion.ai

co reset

Destructive: Reset your account and create a new identity.

Terminalbash
$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.

Terminalbash
$co deploy

Requirements

  • Initialized ConnectOnion project
  • .co/host.yaml (created by co create or co init)
  • Authenticated (co auth)

Example Output

$ co deploy

Deploying to ConnectOnion Cloud...

  Project: my-agent
  Source: /Users/me/my-agent
  Package: 12.3 KB (8 files)
  Env: /Users/me/my-agent/.env (3 keys)

Uploading package to https://oo.openonion.ai...
Deployment: a1b2c3d4
Building container on ConnectOnion Cloud...
  [1/100] status: deploying
  [2/100] status: running

Deployed!
Agent URL: https://my-agent-0x7a9f3b2c.agents.openonion.ai
Dashboard: https://o.openonion.ai/dashboard

Template Deploys

Deploy a built-in template plus any combination of skills — no local project needed:

Terminalbash
$co deploy --template co-ai --name my-agent --skills ~/skills/a ~/skills/b
--templateAny co create template; creates a temporary project, deploys it, cleans up on success
--nameProject name and URL (default {template}-agent) — different skill combos run side by side
--skillsOne or more paths bundled into .co/skills/. A single skill (contains SKILL.md) nests under its directory name; a directory of skills merges its contents

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

co doctor

Comprehensive diagnostics for your ConnectOnion installation.

Terminalbash
$co doctor

What It Checks

System

  • • Version
  • • Python
  • • Environment

Configuration

  • • Config files
  • • Keys
  • • API keys

Connectivity

  • • Backend
  • • Authentication
  • • Network

co ai

AI coding agent in your terminal. Run one-shot prompts or start an interactive agent with full tool access.

One-shot mode - quick code generationbash
$co ai "create a FastAPI hello world app"
Interactive mode - multi-turn conversationbash
$co ai
Web server mode - browser interfacebash
$co ai --port 8000

Learn more: See the complete co ai documentation for advanced features, model selection, and use cases.

co browser

Drive one persistent browser from the shell — call functions directly, or hand a task to the AI agent:

Take a screenshotbash
$co browser go_to example.com
$co browser take_screenshot screenshot.png
Let the AI agent figure out the stepsbash
$co browser do "find the pricing page and take a screenshot"
Screenshot at a specific viewport sizebash
$co browser set_viewport 390 844
$co browser go_to example.com
$co browser take_screenshot mobile.png

Tip: Run co browser help to list every callable function and its arguments. There are no named device presets — pass explicit viewport pixels.

Learn more: See the complete co browser documentation for URL handling, framework examples, and advanced usage.

co outlook

Send, read, and search email from your Outlook account — straight from the terminal. Connect your Microsoft account once with co auth microsoft, then:

Show your inbox (numbered table)bash
$co outlook
Read email #3 from the last listing (marks it read)bash
$co outlook read 3
Send an emailbash
$co outlook send alice@example.com "Quarterly report" "Draft attached, feedback welcome."
Attach files and CC someone (repeat --attach for multiple)bash
$co outlook send alice@example.com "Screenshots" "See attached" --cc bob@example.com --attach shot1.png --attach shot2.png
Schedule delivery: +30m, +2h, or a UTC ISO timebash
$co outlook send alice@example.com "Reminder" "Standup in 30" --at +30m
Pipe a body from stdin with message '-'bash
$git log --oneline -10 | co outlook send alice@example.com "This week" -
Sent mail and searchbash
$co outlook sent
$co outlook search "invoice"

Tip: Scheduled sends (--at) use Exchange deferred delivery — the email waits server-side, so your machine can go offline. Attachments go through Microsoft Graph, which caps the total at about 3 MB.

Learn more: See the Outlook documentation for the agent tool, all CLI options, and troubleshooting.

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

Browser

Browser automation agent with stateful Playwright-backed tools:

  • Stateful browser (open_browser, go_to, click, keyboard_type)
  • Screenshot capture with viewport control
  • Content extraction (get_text, extract_data, get_links_from_page)

Coder

Code-writing agent with file and shell tools:

  • File editing tools (read, write, diff)
  • Shell and bash execution
  • Todo list for multi-step plans

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:

ProviderKey FormatExample
OpenAIsk-... or sk-proj-...sk-proj-abc123...
Anthropicsk-ant-...sk-ant-api03-xyz...
GoogleAIza...AIzaSyAbc123...
Groqgsk_...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
├──host.yaml# 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 AIbash
$co create simple-bot --no-ai --template co-ai
Web research project with AIbash
$co create research-agent --ai --template co-ai
Custom AI agent with descriptionbash
$co create slack-bot --ai --template custom --description "Slack bot that answers questions"
Initialize existing directorybash
$cd my-existing-project
$co init --ai --template co-ai

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:

Terminalbash
$# Use full command
$python -m connectonion.cli.main create
$
$# Or reinstall
$pip uninstall connectonion
$pip install connectonion

Python Version

ConnectOnion requires Python 3.9 or higher. Check your version:

Terminalbash
$python --version

API Key Issues

  • Check key format matches your provider
  • Ensure key is active and has credits
  • Try pasting without quotes or spaces
Previous
Getting Started
Deploy
Next
CLI
co create

Star us on GitHub

If ConnectOnion saves you time, a ⭐ goes a long way — and earns you a coffee chat with our founder.