pangram

pangramcli-demo.mp4

---

pangram is an unofficial terminal client for Pangram AI detection and plagiarism checking. it serves three interaction modes through one behavioral core: a JSON-first command-line interface for scripts and shell pipelines, an interactive terminal user interface for people, and a typed stdio MCP server for AI agents.

documentation | npm | github | contracts

why

pangram's web application is useful for interactive checks, but terminal and agent workflows need a different interface:

• one command surface for AI detection, plagiarism, files, and bulk work
• JSON-first output with stable errors and exit codes
• an interactive TUI with optional local history
• typed MCP tools with billing, filesystem, and mutation safeguards
• signed native releases with package-manager-aware updates

quickstart

linux or macos

install the signed native binary:

curl -fsSL https://github.com/Microck/pangram-cli/releases/latest/download/pangram-installer.sh | sh
pangram --help

the installer places pangram in ~/.local/bin. add that directory to PATH when the installer asks you to.

windows

run the signed PowerShell installer:

irm https://github.com/Microck/pangram-cli/releases/latest/download/pangram-installer.ps1 | iex
pangram --help

using a package manager

npm install -g @microck/pangram-cli

# homebrew
brew install --formula https://github.com/Microck/pangram-cli/releases/latest/download/pangram.rb

# scoop
scoop install https://github.com/Microck/pangram-cli/releases/latest/download/pangram-scoop.json

native archives for Linux, macOS, and Windows are also available from GitHub Releases. see the installation guide for platform details.

authentication

set PANGRAM_API_KEY before the first billable command:

export PANGRAM_API_KEY='...'
pangram auth status

store the key in the protected local credential file without putting it in shell history or process arguments:

printf '%s\n' "$PANGRAM_API_KEY" | pangram auth set --api-key-stdin
pangram auth status

interactive terminals can run pangram auth for masked setup. authentication commands do not submit content or consume credits.

first analysis

run AI detection on literal text:

pangram detect "text to analyze" --max-billable-units 1

read text from a shell pipeline:

printf '%s\n' 'text to analyze' | pangram detect - --max-billable-units 1

run AI detection and plagiarism checks together:

pangram analyze "text to analyze" --max-billable-units 6

use terminal-readable output instead of the default JSON envelope:

pangram detect --format pretty "text to analyze" --max-billable-units 1

open the interactive terminal interface:

pangram

every analysis submits content to Pangram. use --max-billable-units to reject requests above a local spending ceiling. local history and public dashboard links stay disabled by default.

files and bulk jobs

analyze supported documents directly:

pangram detect --file ./paper.pdf --max-billable-units 10
pangram detect --file ./notes.txt --format pretty --max-billable-units 1

preview a bulk JSONL request without credentials or network access:

pangram bulk submit items.jsonl --max-billable-units 20 --dry-run

submit a bulk request and wait for its terminal result:

pangram bulk submit items.jsonl --max-billable-units 20 --wait

media and github shortcuts

transcribe locally, then detect. ffmpeg and whisper-cli (whisper.cpp) must be installed; the first run downloads the ggml model only with --download-model or an interactive yes:

pangram video ./lecture.mp4 --max-billable-units 80 --download-model
pangram youtube 'https://www.youtube.com/watch?v=...' --max-billable-units 80
GH_TOKEN=... pangram pr owner/repo#123 --comments --max-billable-units 5

youtube uses your own yt-dlp install. review comments send only their prose body, never diffs.

a bare pull request, issue, or YouTube URL routes to the matching shortcut, and trailing flags go to that command. any other bare URL is rejected; use pangram detect to analyze a URL as text:

GH_TOKEN=... pangram https://github.com/owner/repo/pull/123 --max-billable-units 5

mcp client

preview the exact configuration edit before writing it:

pangram mcp install --target cursor --dry-run
pangram mcp install --target cursor

restart the client, then call its Pangram detection tool with a positive billable-unit ceiling. MCP startup exposes no history mutations, public links, or file roots unless you enable those capabilities explicitly.

shell completion

generate completion for your shell:

pangram completions bash > ~/.local/share/bash-completion/completions/pangram
pangram completions zsh > ~/.zsh/completions/_pangram
pangram completions fish > ~/.config/fish/completions/pangram.fish

in Nushell, save the module into an autoload directory:

mkdir ($nu.data-dir | path join vendor autoload)
pangram completions nushell | save -f ($nu.data-dir | path join vendor autoload pangram.nu)

for the full authentication, MCP, history, and platform guides, see the documentation.

command surface

available today:

command	purpose
pangram	bare literal text or piped stdin runs AI detection; a bare pull request, issue, or YouTube URL routes to its shortcut; an all-TTY launch opens the TUI
pangram detect	run Pangram 4 AI text detection
pangram plagiarism	run plagiarism checking on text
pangram analyze	run AI detection and plagiarism together on text
pangram video	transcribe a local video with whisper.cpp, then detect
pangram audio	transcribe a local audio file with whisper.cpp, then detect
pangram youtube	download audio with your installed yt-dlp, transcribe, then detect
pangram pr	detect AI writing in a GitHub pull request title, body, and optional comments
pangram issue	detect AI writing in a GitHub issue title, body, and optional comments
pangram comments	detect AI writing in GitHub issue and review comment bodies
pangram auth	configure and inspect API-key authentication
pangram config	inspect and update non-secret configuration
pangram doctor	run local, non-billable diagnostics
pangram bulk	submit and inspect asynchronous bulk detection
pangram task	inspect or wait for a Pangram text task
pangram history	list, show, search, delete, clear, export, and rerun optional local history
pangram mcp	run or install the typed stdio MCP server
pangram agent	print the embedded agent usage guide
pangram skills	list and load version-matched embedded skills
pangram completions	generate a completion script
pangram update	inspect signed update status

privacy and agent safety

local history is disabled by default. when enabled, it stores canonical inputs, results, and task identity in a local SQLite database until you delete them. public Pangram dashboard links are also disabled by default and must be requested explicitly for each submission.

for AI agents, the MCP server enforces strict safeguards. it requires explicit startup capabilities for history mutation, configuration changes, public links, and filesystem access. file inputs are restricted to approved root directories, and billable MCP tools require explicit ceilings to prevent uncontrolled costs.

architecture summary

the runtime uses Rust. a single deep analysis module owns Pangram HTTP behavior, polling, normalization, retries, and task state. the CLI, TUI, and MCP server act as adapters over that module to ensure consistent semantics. documentation lives in a separate TypeScript workspace and consumes generated schemas to stay aligned with the runtime contract.

development status

version 0.1.0 is available through npm and GitHub Releases. observable behavior is defined in docs/contracts.md and enforced through compiled-binary, loopback HTTP, SQLite, PTY, MCP, update, and generated-contract tests.

documentation

• product specification
• architecture specification
• observable contracts
• history contract
• mcp contract
• update contract

disclaimer

this project is unofficial and is not affiliated with, endorsed by, or connected to Pangram Labs, Inc. it is an independent client for documented Pangram APIs.

use of Pangram services remains subject to Pangram's terms, billing, retention, and acceptable-use policies. detection results are probabilistic evidence and should be one signal among many, not a verdict.

license

mit license

Browser regression tests

Run npm ci, npm run docs:build, npx e2e-web install chromium, then npm run test:e2e -w docs-app. The pinned tester-army/e2e tests open every documentation route against the production server. No provider accounts, model agents, billable submissions or update-network operations are used. Native CLI, TUI and MCP acceptance remain in their existing real-process suites.