@visible/cli

Transform technical changes into audience-friendly communication materials.

The Visible CLI helps technical teams analyze code, PRs, and repositories to generate artifacts that can be used for documentation, release notes, tutorials, and more.

Features

• Git Diff Analysis: Analyze git diffs between commits to extract context and generate artifacts
• Pull Request Analysis: Analyze GitHub PRs with automatic context extraction
• AI-Powered Code Exploration: Use "The Detective" agent to intelligently explore and understand codebases
• Artifact Generation: Create structured artifacts ready for documentation generation
• Video Generation: Automatically generate professional tutorial and release videos from your code

Installation

# Install globally from npm
npm install -g @visible/cli

# Or use npx to run without installing
npx @visible/cli --help

Quick Start

# Get help
visible --help

# Analyze the latest commit
visible analyze diff

# Analyze a specific commit range
visible analyze diff HEAD~5..HEAD

# Analyze a pull request
visible analyze pr --url https://github.com/owner/repo/pull/123

# Explore a codebase with AI
visible analyze prompt "how does user authentication work"

Configuration

The CLI requires the following environment variables:

# Required for AI-powered code exploration (analyze prompt)
export OPENAI_API_KEY=sk-your-openai-api-key

# Required for posting artifacts to Visible API
# For local dev, defaults to http://localhost:3000/api and no API key is required
export VISIBLE_API_BASE_URL=https://your-visible-instance.com
export VISIBLE_API_KEY=your-api-key

# Optional: For PR analysis via GitHub API
export GITHUB_TOKEN=ghp-your-github-token

You can set these in your shell profile (.bashrc, .zshrc, etc.) or use a .env file with a tool like direnv.

Commands

visible analyze diff [range]

Analyze git diff between commits to create an artifact.

# Analyze the latest commit
visible analyze diff

# Analyze a specific range
visible analyze diff HEAD~5..HEAD

# Skip posting to API (just preview the artifact)
visible analyze diff --no-post

Options:

• [range] - Git commit range (default: HEAD~1..HEAD)
• --no-post - Skip posting artifact to Visible API
• --video [path] - Generate video (optional: output directory)
• --video-format <format> - Video format: mp4 or webm
• --video-resolution <res> - Resolution: 1080p, 720p, 480p, square, vertical

visible analyze pr

Analyze a pull request to create an artifact.

# Analyze by PR URL
visible analyze pr --url https://github.com/owner/repo/pull/123

# Analyze by PR number (uses current repo)
visible analyze pr --number 123

# Skip posting to API
visible analyze pr --url https://github.com/owner/repo/pull/123 --no-post

Options:

• --url <url> - Pull request URL
• --number <number> - Pull request number (uses current repo)
• --no-post - Skip posting artifact to Visible API
• --video [path] - Generate video (optional: output directory)
• --video-format <format> - Video format: mp4 or webm
• --video-resolution <res> - Resolution: 1080p, 720p, 480p, square, vertical

visible analyze prompt "<query>"

Explore your codebase with an AI agent (The Detective) that intelligently navigates files, follows imports, and understands code relationships.

# Explore a feature
visible analyze prompt "how does user authentication work"

# Understand a specific flow
visible analyze prompt "explain the payment processing flow"

# Document an API endpoint
visible analyze prompt "describe the /api/users endpoint"

# Verbose mode to see agent's reasoning
visible analyze prompt "payment processing flow" --verbose

# Skip posting to API
visible analyze prompt "explain the search feature" --no-post

Options:

• <query> - Natural language prompt describing what to analyze
• -v, --verbose - Show detailed agent activity
• --no-post - Skip posting artifact to Visible API
• --video [path] - Generate video (optional: output directory)
• --video-format <format> - Video format: mp4 or webm
• --video-resolution <res> - Resolution: 1080p, 720p, 480p, square, vertical

How The Detective Agent works:

1. Searches for files related to your query
2. Reads relevant files and follows imports
3. Finds where components/functions are used (entry points)
4. Traces data flow through the codebase
5. Identifies key data structures and schemas
6. Produces a structured artifact with:
   • Entry points (how the feature is triggered)
   • Data flow (step-by-step explanation)
   • Key files and their purposes
   • Data structures involved
   • Usage examples from the codebase

Video Generation

Generate professional videos that showcase your features, explain changes, or create tutorials.

# Generate a video from feature analysis
visible analyze prompt "how does checkout work" --video

# Generate a video from git changes
visible analyze diff --video

# Customize resolution and format
visible analyze pr --url https://github.com/org/repo/pull/123 \
  --video ./videos \
  --video-resolution 1080p \
  --video-format mp4

Resolution presets: 1080p, 720p, 480p, square (Instagram), vertical (TikTok/Stories)

Videos include:

• AI-generated UI mockups matching your app's design
• Code highlights with syntax highlighting
• Professional transitions and animations
• Your color scheme and branding

See docs/VIDEO-GENERATION.md for the complete guide.

Example Workflow

# 1. Navigate to your project
cd your-project

# 2. Set up environment
export OPENAI_API_KEY=sk-xxx
export VISIBLE_API_BASE_URL=http://localhost:3000
# API key is optional when using localhost
export VISIBLE_API_KEY=my-key

# 3. Explore a feature and create an artifact
visible analyze prompt "how do users create new projects"

# 4. The CLI will output:
#    - Investigation results (entry points, data flow, key files)
#    - Post the artifact to the Visible API
#    - Return a URL to continue in the dashboard

# 5. Generate a video (optional)
visible analyze prompt "how do users create new projects" --video

Artifact Output

All commands generate artifacts with the following structure:

interface Artifact {
  title: string;
  description: string;
  source: {
    type: "pr" | "commit" | "code-section" | "repository";
    reference: string;
    url?: string;
  };
  context: {
    summary: string;
    technicalDetails: string[];
    affectedComponents: string[];
    breakingChanges: boolean;
    keywords: string[];
  };
  guidelines: string[];
}

Programmatic Usage

You can also use the CLI as a library:

import { analyzeDiff, analyzePR, investigateFeature } from "@visible/cli";

// Analyze a git diff
const diffResult = await analyzeDiff("HEAD~1..HEAD");

// Analyze a PR
const prResult = await analyzePR({ url: "https://github.com/org/repo/pull/123" });

// Investigate a feature
const investigation = await investigateFeature("how does authentication work", {
  verbose: true,
  onToolCall: (name, args) => console.log(`Tool: ${name}`),
});

Requirements

• Node.js >= 20
• Git (for diff/PR analysis)
• OpenAI API key (for AI-powered exploration)
• GitHub CLI (gh) for PR analysis (optional but recommended)

Troubleshooting

"Missing OPENAI_API_KEY"

Set the OPENAI_API_KEY environment variable with your OpenAI API key.

"Not in a git repository"

Make sure you're running the CLI from within a git repository.

PR analysis fails

Ensure you have the GitHub CLI (gh) installed and authenticated:

gh auth login

License

MIT

Contributing

See the main Visible repository for contribution guidelines.