Why We Choose Progressive Disclosure Over Configuration Questionnaires

September 2025 • Design Decision #006

Most framework CLIs bombard users with questions that don't matter yet. We chose progressive disclosure: start fast, decide later, respect intelligence.

The Problem with Traditional CLIs

Typical framework initialization:

What's your project description? (I don't know, I just started)
Choose your testing framework? (Let me build something first)
Configure your linter settings? (Please, just let me code)
Set up CI/CD pipeline? (It's my first 5 seconds with this tool)

This approach assumes users know everything upfront. Reality: they don't, and they shouldn't have to.

Our Philosophy: Progressive Disclosure

< 30s

To working code

Questions maximum

Required configs

The Two-Command Strategy

terminal

# Outside a project
co create my-agent  # Creates new directory

# Inside a project
co init             # Uses current directory

Why both? Because context matters:

Outside: Users want to create a new space
Inside: Users have already decided where to work

This isn't redundancy; it's respecting user intent. Django does this, Rails does this, and for good reason.

Minimal Questions, Maximum Intelligence

Our setup asks only what matters RIGHT NOW:

1. Enable AI? - Determines available templates
2. API key - Only if AI enabled, with auto-detection
3. Template - With previews so users know what they get

That's it. Three decisions max.

Compare to typical CLIs: Create-react-app (5+ questions), Vue CLI (10+ questions), Yeoman generators (often 15+ questions).

Smart API Key Detection

api_detection.py

if api_key.startswith('sk-proj-'):
    # OpenAI project key
elif api_key.startswith('sk-ant-'):
    # Anthropic
elif api_key.startswith('gsk_'):
    # Groq

The key format already tells us the provider. Why make users answer what we can infer?

Template Preview, Not Template Guessing

📦 Minimal - Simple starting point
  ├── agent.py (50 lines) - Basic agent with example tool
  ├── .env - API key configuration
  └── .co/ - Agent identity & metadata

Users shouldn't have to guess. Show them, let them choose, move on.

What We Don't Ask

We Skip

Project description
Author name
License type
Version number
Test framework
Package manager

We Do

Create working code immediately
Use sensible defaults everywhere
Show clear next steps
Get out of the way

Beautiful by Default

We use colors and emojis for clarity, not decoration:

✅Green = Success

⚠️Yellow = Warning

❌Red = Error

📁Icons = Visual scanning

But we respect terminal preferences: works in non-color terminals, copy-paste friendly, no ASCII art or unnecessary flair.

Results: User Delight

30s

to running agent

questions max

required configs

command to start

Conclusion

Good CLI UX isn't about asking fewer questions - it's about asking the RIGHT questions at the RIGHT time. Everything else should be invisible, automatic, or optional.

The best tool is one you forget you're using. That's what we built.

Simplicity is the ultimate sophistication in CLI design.

Why "Address" Over "Identity"

Auto-Debug Design Evolution