CLI Installation & Usage

The AgentGIF CLI lets you upload, record, search, and manage terminal GIFs from your terminal. Available in 5 languages — choose the one that fits your stack.

Install

The CLI is published to all major package registries. Each implementation provides the same core commands.

Language	Install Command	Registry
Python	`pip install agentgif`	PyPI
Node.js	`npm install -g @agentgif/cli`	npm
Go	`go install github.com/agentgif/cli@latest`	pkg.go.dev
Rust	`cargo install agentgif`	crates.io
Ruby	`gem install agentgif`	RubyGems

Verify the installation:

agentgif --version
agentgif --help

Authentication

Before uploading or managing GIFs, authenticate with your GitHub account:

agentgif login

This opens your browser for GitHub OAuth. After authorization, the CLI stores your API key locally at ~/.config/agentgif/config.json.

Alternatively, set your API key directly:

agentgif login --api-key YOUR_API_KEY

Get your API key from Settings → API Key.

Check your auth status:

agentgif whoami
# → @yourname (authenticated)

Upload

Upload a GIF with metadata:

agentgif upload demo.gif \
  --title "Docker Compose Up" \
  --command "docker compose up -d" \
  --tags docker,compose,containers \
  --description "Starting services with Docker Compose"

Upload Options

Flag	Description
`--title`	GIF title (required)
`--command`	The command demonstrated
`--tags`	Comma-separated tags
`--description`	Description text
`--cast`	Path to asciinema v2 cast file
`--shell`	Shell used (bash, zsh, fish)
`--visibility`	`public` (default) or `unlisted`
`--open`	Open the GIF page in your browser after upload

Upload with Cast File

Including a cast file enables the machine-readable layer for AI agents:

agentgif upload demo.gif --cast demo.cast --title "Git Rebase" --tags git

Record with VHS

The Python CLI can record terminal sessions directly using VHS (must be installed separately).

# Record from a VHS tape file
agentgif record demo.tape --theme dracula

# Record and immediately upload
agentgif record demo.tape --upload --title "My Demo" --tags demo

Record Options

Flag	Description
`--theme`	Terminal theme (see themes)
`--output`	Output file path (default: same name as tape with .gif)
`--upload`	Upload immediately after recording
`--title`	Title for auto-upload
`--tags`	Tags for auto-upload

VHS must be installed separately: brew install vhs (macOS) or see the recording guide.

Search

Search across all public GIFs:

agentgif search "docker compose"

Output shows GIF ID, title, command, and view count in a formatted table.

Search Filters

# Filter by tag
agentgif search "build" --tag docker

# Filter by shell
agentgif search "alias" --shell zsh

# Sort by views instead of relevance
agentgif search "git" --sort views

Manage GIFs

List Your GIFs

agentgif list
agentgif list --limit 50

View GIF Details

agentgif info xK9mQ2pL

Edit a GIF

agentgif edit xK9mQ2pL --title "New Title" --tags git,rebase

Delete a GIF

agentgif delete xK9mQ2pL
# → Are you sure? (y/N)

Configuration

The CLI stores configuration at ~/.config/agentgif/config.json:

{
  "api_key": "ag_xxxxxxxxxxxx",
  "api_url": "https://agentgif.com/api/v1",
  "default_theme": "catppuccin-mocha",
  "default_shell": "zsh",
  "auto_open": false
}

Environment Variables

Environment variables override config file settings:

Variable	Description
`AGENTGIF_API_KEY`	API key (overrides config)
`AGENTGIF_API_URL`	API base URL
`AGENTGIF_THEME`	Default VHS theme

Useful in CI/CD pipelines:

AGENTGIF_API_KEY=${{ secrets.AGENTGIF_KEY }} agentgif upload dist/demo.gif --title "CI Build"

← Back to Documentation · Embed Guide →