Finalcliper Logo
Full Documentation & Setup Guide

Finalcliper Docs

Learn how to run Finalcliper locally, configure Google ADK2 AI agents, connect YouTube Studio & Instagram Analytics, and deploy securely online.

Local Setup

Run the app on localhost with Bun and Node in under 2 minutes.

Deploy Online

Production deployment on Vercel, Google Cloud Run, or Docker.

AI Agents & Copilot

Google ADK2 Analysis Agent, Booming Radar, and timeline cuts.

Analytics APIs

Google Cloud & Meta App OAuth setup with 1-click token handoff.

1

How to Run Locally

Prerequisites

  • Bun: Version 1.2.x or newer (install Bun).
  • Node.js: Version 18+ (used by Turborepo & Next.js).
  • Gemini API Key: Free from Google AI Studio.

Step 1: Clone Repository & Install Dependencies

# 1. Clone the repository

git clone https://github.com/your-username/kneecap.git

cd kneecap


# 2. Install all workspace dependencies via Bun

bun install

Step 2: Configure Environment Variables

Create a .env.local file in apps/web/:

# Base App Configuration

NEXT_PUBLIC_APP_URL=http://localhost:3000

NODE_ENV=development


# Google Gemini AI Key (for AI Copilot, Video Scripting, & ADK2 Agents)

GEMINI_API_KEY=AIzaSy...


# Optional: YouTube Studio OAuth credentials (Google Cloud Console)

YOUTUBE_CLIENT_ID=340978777180-xxx.apps.googleusercontent.com

YOUTUBE_CLIENT_SECRET=GOCSPX-xxx


# Optional: Instagram Graph API OAuth credentials (Meta Developer Portal)

INSTAGRAM_CLIENT_ID=your_meta_app_id

INSTAGRAM_CLIENT_SECRET=your_meta_app_secret

Step 3: Launch Local Development Server

# Start local Next.js Turbopack development server

bun dev


# Or run only the web workspace directly

bun run dev:web

Open http://localhost:3000 in your browser. The app runs local-first with zero database requirements!

Step 4: Run Tests & Type Checks

# Run full test suite (68 tests across agents, timeline, and analytics)

cd apps/web && bun test


# Validate TypeScript types

bun x tsc --noEmit

2

How to Deploy Online

Option A: Deploy to Vercel (Recommended)

  1. Push your code to GitHub.
  2. Import the repository into Vercel.
  3. Set the Root Directory to apps/web.
  4. Add your Environment Variables (GEMINI_API_KEY, NEXT_PUBLIC_APP_URL=https://yourdomain.com, and OAuth credentials).
  5. Click Deploy. Vercel automatically builds and serves the Next.js app on edge serverless infrastructure.

Option B: Deploy to Google Cloud Run / Docker

# Build production container

docker build -t finalcliper-web -f apps/web/Dockerfile .


# Run container on port 3000

docker run -p 3000:3000 -e GEMINI_API_KEY="your_key" -e NEXT_PUBLIC_APP_URL="https://yourdomain.com" finalcliper-web

Production OAuth Redirect URI Checklist

When deploying on your live domain (e.g. https://app.finalcliper.com), make sure to add the exact callback URLs to your Google Cloud Console and Meta Developer App:

  • https://yourdomain.com/api/youtube/oauth/callback
  • https://yourdomain.com/api/instagram/oauth/callback
3

Google ADK2 AI Agents & Copilot Features

ADK2 Analysis Agent

Deeply analyzes historical performance metrics from YouTube Studio and Instagram Reels to diagnose retention drop-offs and formulate ready-to-produce video blueprints.

Command: "analyze" or "auto create"

Live Booming Creator Radar

Scans the live 2026 creator ecosystem using Google search grounding to find the fastest-growing viral formats, retention hooks, and pacing styles right now.

Command: "booming" or "trending now"

Natural Language Video Cutting

Instant 0ms latency timeline control. Execute cuts at playhead, split left/right, jump to timestamp, or create rhythm pacing cuts every 3 seconds.

Commands: "cut here", "cut every 3s", "split at 5s"

Veo Video & TTS Narration

Generates cinematic Veo video shots and neural text-to-speech voiceovers automatically imported into your multi-track timeline as complete editable elements.

Command: "write a script on [topic]"
4

YouTube & Instagram Analytics API Configuration

1. Enabling YouTube Data API v3

  1. Go to the Google Cloud Console API Library.
  2. Select your project (or create one) and click Enable for YouTube Data API v3.
  3. Under Credentials, create an OAuth 2.0 Client ID (Web application) with Authorized Redirect URI: http://localhost:3000/api/youtube/oauth/callback.

2. Instagram Graph API Setup

  1. Create an app on the Meta for Developers Portal with Instagram Graph API permissions.
  2. In development mode, add your Instagram user under Roles → Instagram Testers and accept the invitation in Instagram Settings.
  3. Add Authorized Redirect URI: http://localhost:3000/api/instagram/oauth/callback.

💡 Manual Token Fallback (Zero-OAuth Setup)

If you prefer not to configure full OAuth apps, you can directly paste your Google Access Token or Instagram Graph Token in /analytics/settings and /analytics/youtube/settings for instant sync.

Ready to start creating?

Launch the video editor or jump into your analytics dashboard.

Launch EditorView Analytics