@aperovn/funnel-cli

CLI tool for deploying AperoFunnel projects.

Installation

npm install -g @aperovn/funnel-cli
# or
bun install -g @aperovn/funnel-cli

Commands

aperofunnel config

Manage CLI configuration. Run config set-url once before login.

aperofunnel config set-url <url>   # Persist API base URL
aperofunnel config show            # Print current URL + auth status
aperofunnel config clear --force   # Remove config file

• set-url validates the URL, probes ${url}/health (3s timeout, warn-only), and writes to ~/.aperofunnel/config.json.
• show never prints the API key — only whether one is set.
• All other commands fail fast if the URL is not configured.

aperofunnel login

Authenticate with AperoFunnel API. Requires config set-url to have been run first.

aperofunnel login

• Prompts for API key (starts with af_)
• Validates key against the configured API URL
• Stores in ~/.aperofunnel/config.json

aperofunnel init [name]

Initialize a new AperoFunnel project.

aperofunnel init [name] [--use-npm]

• Creates Next.js project with @aperovn/funnel-sdk preconfigured
• Sets up aperofunnel.json config file
• Installs dependencies (uses bun by default, --use-npm to use npm)
• Bundles a Claude Code skill at .claude/skills/apero-funnel/ — see AI Integration

aperofunnel deploy

Deploy funnel to AperoFunnel platform.

aperofunnel deploy [--skip-scan]

Pipeline:

1. Read aperofunnel.json config
2. Validate @aperovn/funnel-sdk in dependencies
3. Check Node.js version
4. Run security scan (npm audit or socket-cli)
5. Build Next.js static export
6. Check bundle budget (250KB JS / 500KB total)
7. Create tar.gz bundle
8. Sign manifest (SHA256 + HMAC-SHA256)
9. Upload to API
10. Print draft URL + version ID

Exit conditions:

• Critical vulnerabilities found (use --skip-scan to bypass, not recommended)
• Build fails
• Bundle budget exceeded

aperofunnel publish <version-id>

Publish a draft version to live.

aperofunnel publish <version-id>

aperofunnel rollback <version-id>

Rollback to a previous version.

aperofunnel rollback <version-id>

aperofunnel list

List all versions of the funnel.

aperofunnel list

Shows version ID, status (draft/live/archived), creation date, and bundle sizes.

Configuration

aperofunnel.json

Required in project root:

{
  "funnelId": "fn_xxx",
  "buildDir": "out",
  "budget": {
    "maxJsKb": 250,
    "maxTotalKb": 500
  }
}

• funnelId: Funnel ID from dashboard (workspaceId resolved automatically at deploy time)
• buildDir: Next.js export output directory (default: out)
• budget.maxJsKb: Maximum JS bundle size in KB
• budget.maxTotalKb: Maximum total bundle size in KB

AI Integration

Projects scaffolded via aperofunnel init ship with a Claude Code skill at .claude/skills/apero-funnel/. The skill teaches Claude how to use the CLI and @aperovn/funnel-sdk accurately — commands, component props, and patterns straight from the published versions.

How it works:

• Claude Code auto-discovers the skill on session start
• SKILL.md is a decision matrix routing common asks (build a quiz, wire up Stripe checkout, add session tracking) to detailed reference docs under references/
• Version-stamped at scaffold time to match the bundled CLI + SDK

Other AI tools: Point Cursor / Aider / Copilot at .claude/skills/apero-funnel/SKILL.md — it's a single-file entry point with relative links to detail docs.

Updating the skill: The bundled copy is frozen at scaffold time. To pull newer guidance, scaffold a fresh project with the latest CLI and copy .claude/skills/apero-funnel/ over your existing project.

Migrating from 0.2.x

The --api-url flag was removed in 0.3.0. Set the API URL once with config set-url instead:

# Before (0.2.x)
aperofunnel login --api-url https://app.example.com

# After (0.3.0+)
aperofunnel config set-url https://app.example.com
aperofunnel login

CI scripts must invoke config set-url before any other command. The location can be overridden via APEROFUNNEL_CONFIG_DIR for sandboxed environments.

Security

• API keys stored in ~/.aperofunnel/config.json (OS keychain integration planned)
• Manifest signature proves scan ran on dev's machine
• Build output (static HTML/JS/CSS) uploaded, not source code
• Socket.dev/npm audit results uploaded for verification

Requirements

• Node.js >= 18.0.0
• Next.js project with output: 'export' in next.config.js
• @aperovn/funnel-sdk in dependencies

Development

# Install dependencies
bun install

# Build
bun run build

# Type check
bun run typecheck

# Test locally (from package dir)
node dist/index.js --help

License

MIT