Package Exports

@nocodeveloper/zoe-cli
@nocodeveloper/zoe-cli/dist/cli/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@nocodeveloper/zoe-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Zoe CLI

Zero config, maximum power. Zoe is an AI-powered coding assistant that manages everything in the backend through InsForge.

Quick Start

# 1. Install
npm install -g @nocodeveloper/zoe-cli

# 2. Login with GitHub (auto-configures everything)
zoe login

# 3. Start coding!
zoe

That's it. No API keys to copy, no .env files, no configuration. Zoe gets your OpenRouter API key automatically from InsForge secrets.

Features

Zero Configuration - Just login and start working. API keys are managed through InsForge secrets.
GitHub OAuth - Secure authentication via InsForge
OpenRouter Integration - API key loaded automatically from InsForge secrets. Supports 300+ models.
Project Intelligence - Automatic project scanning for context-aware AI assistance
Streaming Responses - Real-time AI response streaming in the terminal
Slash Commands - /model, /help, /scan while in chat
Tool System - File read/write/edit, glob, grep, shell execution, directory listing
Session Persistence - Chat history saved automatically

How It Works

Architecture

┌─────────────────────────────────────────────────────┐
│                    Zoe CLI                           │
├─────────────────────────────────────────────────────┤
│  zoe login    →  InsForge OAuth (GitHub)            │
│               →  Gets OpenRouter API Key from       │
│                  InsForge secrets                   │
├─────────────────────────────────────────────────────┤
│  zoe          →  Interactive chat                   │
│               →  Calls OpenRouter API directly      │
│               →  Streams response in real-time      │
├─────────────────────────────────────────────────────┤
│  zoe "task"   →  One-shot task execution            │
│               →  Streams response, then exits       │
└─────────────────────────────────────────────────────┘

Authentication Flow

zoe login connects to InsForge using your project's .insforge/project.json
Fetches the OPENROUTER_API_KEY secret from InsForge Dashboard
Authenticates via GitHub OAuth through InsForge
Saves session to .zoe/config.json
Every AI call uses the cached API key — no user interaction needed

AI Call Flow

┌──────────┐     ┌──────────┐     ┌──────────────┐
│  Zoe CLI │────>│ InsForge │────>│   OpenRouter │
│          │     │ Secrets  │     │   API        │
│  prompt  │     │ API Key  │     │   streaming  │
│      <───│─────│──────────│─────│   response   │
└──────────┘     └──────────┘     └──────────────┘

Commands

Command	Description
`zoe`	Start interactive chat
`zoe "task description"`	Run a task directly and exit
`zoe login`	Login with GitHub (fetches API key from InsForge)
`zoe logout`	Logout and clear session
`zoe whoami`	Show current logged in user
`zoe models`	List available AI models
`zoe use <model>`	Select a model (e.g. `deepseek/deepseek-v4-pro`)
`zoe scan`	Scan project structure for AI context
`zoe doctor`	Analyze project health
`zoe summary`	Show project overview

Slash Commands (in Chat)

Command	Description
`/model <name>`	Switch to a different model
`/help`	List available commands
`/scan`	Re-scan project structure
`exit` / `quit`	Exit Zoe

Configuration

Zoe stores configuration in .zoe/config.json. You rarely need to touch it — everything is automatic.

{
  "model": "deepseek/deepseek-v4-pro",
  "maxSteps": 100,
  "maxCost": 10,
  "autoScan": true,
  "session": {
    "user": "Joel Araujo",
    "email": "user@email.com",
    "projectId": "proj_xxx"
  }
}

InsForge Secrets Setup

Zoe needs one secret in your InsForge project dashboard:

Secret Name	Description
`OPENROUTER_API_KEY`	Your OpenRouter API key (`sk-or-v1-...`)

To add it:

Go to your InsForge Dashboard
Open your project → Settings → Secrets
Add OPENROUTER_API_KEY with your OpenRouter key as the value
Run zoe login to authenticate

Zoe also checks for these fallback secrets: DEEPSEEK_API_KEY, OPENAI_API_KEY.

Project Intelligence

Zoe automatically scans your project to understand its structure, languages, and dependencies:

zoe scan      # Manual scan
zoe doctor    # Check for issues
zoe summary   # View project overview

Scan results are saved in .zoe/project-intelligence.json and used by the AI for context-aware assistance.

Project Structure

zoe-cli/
├── src/
│   ├── cli/
│   │   ├── index.ts            # Entry point with Commander
│   │   └── commands/
│   │       ├── login.ts        # GitHub OAuth + secrets
│   │       ├── chat.ts         # Interactive chat with display
│   │       ├── scan.ts         # Project scanner
│   │       └── ...             # Other commands
│   ├── core/
│   │   ├── agent.ts            # OpenRouter API agent
│   │   ├── config.ts           # Configuration manager
│   │   ├── insforge.ts         # InsForge client + secrets
│   │   ├── intelligence.ts     # Project scanning engine
│   │   ├── auth.ts             # Authentication helpers
│   │   └── session.ts          # Session persistence
│   ├── tools/                  # 7 file system tools
│   │   ├── index.ts
│   │   ├── file-read.ts
│   │   ├── file-write.ts
│   │   ├── file-edit.ts
│   │   ├── glob.ts
│   │   ├── grep.ts
│   │   ├── list-dir.ts
│   │   └── shell.ts
│   └── ui/
│       ├── display.ts          # Welcome screen
│       ├── logo.ts             # ASCII logo
│       ├── styles.ts           # ANSI styles
│       └── ...                 # UI utilities
├── .zoe/                       # Local data
│   ├── config.json
│   ├── project-intelligence.json
│   └── sessions/
├── package.json
├── tsconfig.json
└── README.md

Development

# Clone
git clone https://github.com/nocodeveloper/zoe-cli.git
cd zoe-cli

# Install
npm install

# Build
npm run build

# Test locally
node dist/cli/index.js

JSPM

@nocodeveloper/zoe-cli