CLI 安装与使用

AgentGIF CLI 让您可以从终端上传、录制、搜索和管理终端 GIF。提供 5 种语言版本——选择最适合您技术栈的那个。

安装

CLI 已发布到所有主要包注册表，每种实现提供相同的核心命令。

语言	安装命令	注册表
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

验证安装：

agentgif --version
agentgif --help

身份验证

在上传或管理 GIF 之前，先使用您的 GitHub 账户进行身份验证：

agentgif login

这将打开浏览器进行 GitHub OAuth 授权。授权完成后，CLI 会将您的 API 密钥本地存储在 ~/.config/agentgif/config.json。

或者，直接设置您的 API 密钥：

agentgif login --api-key YOUR_API_KEY

Get your API key from Settings → API Key.

查看认证状态：

agentgif whoami
# → @yourname (authenticated)

上传

上传附带元数据的 GIF：

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

上传选项

标志	描述
`--title`	GIF 标题（必填）
`--command`	演示的命令
`--tags`	逗号分隔的标签
`--description`	描述文本
`--cast`	asciinema v2 cast 文件路径
`--shell`	使用的 Shell（bash、zsh、fish）
`--visibility`	`public`（默认）或 `unlisted`
`--open`	上传后在浏览器中打开 GIF 页面

附带 Cast 文件上传

附带 cast 文件可启用 AI 代理的机器可读层：

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

使用 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

录制选项

标志	描述
`--theme`	Terminal theme (see themes)
`--output`	输出文件路径（默认：与 tape 文件同名，扩展名为 .gif）
`--upload`	录制完成后立即上传
`--title`	自动上传的标题
`--tags`	自动上传的标签

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

搜索

搜索所有公开 GIF：

agentgif search "docker compose"

输出以格式化表格显示 GIF ID、标题、命令和查看次数。

搜索过滤

# 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

管理 GIF

列出你的 GIF

agentgif list
agentgif list --limit 50

查看 GIF 详情

agentgif info xK9mQ2pL

编辑 GIF

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

删除 GIF

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

配置

CLI 将配置存储在 ~/.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
}

环境变量

环境变量会覆盖配置文件设置：

变量	描述
`AGENTGIF_API_KEY`	API 密钥（覆盖配置）
`AGENTGIF_API_URL`	API 基础 URL
`AGENTGIF_THEME`	默认 VHS 主题

适用于 CI/CD 流水线：

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

← 返回文档 · 嵌入指南 →