@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

``bash


Install globally from npm

npm install -g @visible/cli

Or use npx to run without installing

npx @visible/cli --help
`

Quick Start

`bash


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:

`bash


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

$3

Analyze git diff between commits to create an artifact.

`bash


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 - Video format: mp4 or webm
- --video-resolution - Resolution: 1080p, 720p, 480p, square, vertical

$3

Analyze a pull request to create an artifact.

`bash


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

$3

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

`bash


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:
- - 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 - Video format: mp4 or webm
- --video-resolution - 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.

`bash


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

`bash


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:

`typescript
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:

`typescript
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

$3

Set the OPENAI_API_KEY environment variable with your OpenAI API key.

$3

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

$3

Ensure you have the GitHub CLI (gh) installed and authenticated:
`bash
gh auth login
``

License

MIT

Contributing

See the main Visible repository for contribution guidelines.