Quickstart

create-supyagent-app scaffolds a complete Next.js chatbot with Supyagent Cloud integrations, chat persistence, and a ready-to-use UI.

Create Your App

npx create-supyagent-app my-app

The CLI walks you through four prompts:

Prompt	Options	Default
AI provider	Anthropic (Claude), OpenAI (GPT), OpenRouter (any model)	—
Agent mode	Skills (token-efficient, recommended), Tools (rich tool definitions)	Skills
Database	SQLite (local dev), PostgreSQL (production)	—
Authentication	Login via browser (recommended), Paste API key manually	Browser

Non-Interactive Mode

Pass all options as flags to skip prompts:

npx create-supyagent-app my-app \
  --provider anthropic \
  --db sqlite \
  --mode skills \
  --supyagent-api-key sk_live_... \
  --anthropic-api-key sk-ant-...

Flag	Values
`--provider`	`anthropic`, `openai`, `openrouter`
`--db`	`sqlite`, `postgres`
`--mode`	`skills`, `tools`
`--model`	Custom model ID (e.g., `claude-sonnet-4-6-20250620`)
`--supyagent-api-key`	Your Supyagent API key
`--anthropic-api-key`	Anthropic API key (when using `--provider anthropic`)
`--openai-api-key`	OpenAI API key (when using `--provider openai`)
`--openrouter-api-key`	OpenRouter API key (when using `--provider openrouter`)

API Key Resolution

The CLI resolves API keys in this order:

CLI flags (--supyagent-api-key, --anthropic-api-key, etc.)
Environment variables (SUPYAGENT_API_KEY, ANTHROPIC_API_KEY, etc.)
.env files (walks up from cwd, closest file wins)
Interactive prompt (browser login or manual entry)

What Gets Scaffolded

my-app/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── chat/route.ts       # AI chat endpoint (streamText + skills)
│   │   │   ├── chats/route.ts      # List/create chats
│   │   │   ├── chats/[id]/route.ts # Get/delete a chat
│   │   │   ├── me/route.ts         # Account info endpoint
│   │   │   └── jobs/[id]/route.ts  # Background job status
│   │   ├── chat/page.tsx           # Chat UI page
│   │   ├── chat/[id]/page.tsx      # Chat by ID
│   │   ├── layout.tsx              # Root layout
│   │   └── page.tsx                # Home page
│   ├── components/
│   │   └── supyagent/tools/        # Per-provider tool renderers
│   ├── hooks/                      # React hooks
│   └── lib/                        # Prisma client, utilities
├── prisma/
│   └── schema.prisma               # Chat + Message models
├── .env.local                      # API keys (auto-populated)
├── package.json
└── next.config.ts

The key file is src/app/api/chat/route.ts — this is where the AI SDK's streamText connects to Supyagent Cloud tools. See the API Route Example for a detailed walkthrough.

Running the App

The CLI automatically installs dependencies, sets up the database, and starts the dev server:

✔ Scaffolded project
✔ Installed dependencies
✔ Database ready
Starting dev server...

Open http://localhost:3000 to start chatting. Your agent has access to all integrations you've connected on supyagent.com.

Manual Setup

If you need to set up manually (e.g., after cloning):

cd my-app
npm install
npx prisma generate
npx prisma db push
npm run dev

Skills vs Tools Mode

Mode	How it works	Best for
Skills	Agent calls `loadSkill` to fetch docs on demand, then `apiCall` for HTTP requests. Only loads what's needed.	Production apps — lower token usage
Tools	All integration tools are loaded upfront as AI SDK tool definitions.	Prototyping — simpler mental model

Both modes use the same Supyagent Cloud API under the hood. You can switch modes by changing how you initialize tools in the API route.

What's Next

Client — Deep dive into the supyagent() client API
Built-in Tools — Bash execution, image viewing, and skill tools
Persistence — Chat history with Prisma
Cloud Integrations — Connect Google, Slack, GitHub, and more on the dashboard

Quickstart

On this page