@glbgpt/cli

中文文档
0.2.34发布于 2026/11/16ES Module近 30 天下载 5659

GlobalGPT in your terminal — chat, image and video generation, and an exec entry point for scripts and agents.

原始使用文档
文档目录14 节
  1. Install
  2. Commands
  3. Chat
  4. Memory
  5. Account
  6. Images and video
  7. Audio and 3D
  8. Models and tasks
  9. exec — non-interactive
  10. mcp — use from other agents
  11. skill — teach agents to drive the CLI
  12. config
  13. Notes
  14. Development

GlobalGPT CLI

GlobalGPT in your terminal — chat, image and video generation, and an exec entry point for scripts and other agents. You sign in with your GlobalGPT account (no API key); billing is your normal account balance.

Requires Node.js ≥ 22.

Install

npm install -g @glbgpt/cli

Installs two interchangeable commands: glbgpt and globalgpt.

glbgpt login   # authorize in your browser
glbgpt         # start chatting

Commands

Run glbgpt <command> --help for the full flags of any command.

Chat

CommandWhat it does
glbgptStart the interactive chat TUI.
glbgpt "<prompt>"Start the TUI with a first message.
glbgpt resume last · glbgpt resume <id>Resume a previous conversation.

Inside the TUI, type / for commands: /model /models /image /video /tasks /status /permissions /compact /memory /diff /undo /export /account /transactions /cost /login /logout /new /resume /help /exit. /diff shows working-tree changes (plus untracked files); /undo puts back the files the assistant's last turn wrote or edited (run it again to go a turn further back; changes made by shell commands are not tracked); /export writes the conversation to a markdown file. On multi-step tasks the model keeps a visible plan checklist, and when it hits a decision only you can make it asks with an interactive picker (↑/↓ or a number key; Esc lets it proceed on its own judgment). Attach images with @image (last generation), Ctrl+V or @clipboard, or @./photo.png. Multi-line: end a line with \ then Enter (or Ctrl+J); plain Enter sends; Esc interrupts. The composer takes the usual readline edits (Ctrl+A/E, Ctrl+W, Ctrl+U/K, Alt+←/→), Ctrl+R searches past messages, long pastes collapse to a [Pasted text #N] placeholder, and ? on an empty prompt lists every shortcut. In an approval, Tab denies with a note telling the model what to do instead. Use ↑/↓ to browse commands in a short terminal. In /model, type part of a model name or description to filter the list. The check mark shows the model in use and the arrow shows the one Enter will select.

Long tool results show a compact preview. Press Ctrl+O to read the retained output, ←/→ to switch between completed tools, and PgUp/PgDn to page through a log. Press Esc or Ctrl+O to return to your draft.

On tool-capable models the assistant can also read files under the directory you started glbgpt in (read-only — list, read, glob, grep) to answer questions about them, search the web when current information matters (a small per-search credit charge applies, at most a few searches per message), and fetch public web pages by URL (free).

Coding tools

On tool-capable models the assistant can also run shell commands, create files, and edit files in your workspace — every command and file change asks for your approval first ([y] allow once, [a] remember for this session, [p] remember for this project, [n] deny). Diffs are shown before an edit runs. Project instructions in AGENTS.md or CLAUDE.md (from the repository root down to the current directory) are picked up automatically (--no-project-context to skip). Long-running commands (dev servers, watchers) can run in the background — the assistant starts them detached, polls their output, and they are stopped when the CLI exits. Commands can run in a sub-directory of the workspace (the approval says which).

File search uses ripgrep when rg is installed (much faster on large repositories) and a built-in matcher otherwise. Inside a git repository, search skips files matched by .gitignore.

The approval prompt shows the scope remembered by a/p: a command prefix, the exact command, or a directory for file writes/edits. Python interpreters, compound commands, and find/sed/awk (whose flags can delete or rewrite files) require an exact-command approval: changing the command or an inline script asks again. Approving file writes does not approve shell commands.

Long conversations compact automatically: when the history approaches the model's context limit the older part is summarized (one model call) and the conversation continues seamlessly — /compact triggers it manually. The full history always stays on disk.

Permission modes — switch with /permissions <mode>, Shift+Tab (cycles default → accept-edits → auto), or start with --permission-mode <mode>:

ModeBehavior
defaultAsk before every command and file write.
accept-editsFile writes run without asking; commands still ask.
autoFile writes and shell commands run without asking; commands run in a sandbox.
yoloNothing asks (also --yolo). Dangerous — use only in disposable environments.

Auto mode runs each shell command inside the macOS sandbox (sandbox-exec): it can read the machine and write inside the workspace and temp directories, but has no network, cannot change .git, and cannot read ~/.ssh, ~/.aws, the CLI's own credentials and similar. When a command fails because of the sandbox (an npm install, a git commit, a request to a server), you are asked whether to run it outside; "always" remembers that command prefix as usual. On systems without a sandbox (Linux and Windows for now, or GLBGPT_SANDBOX=off) auto mode runs only plain read-only commands (ls, git status, rg, ...) unasked; everything else asks.

Dangerous commands (sudo, forced/recursive rm, ...) always ask individually and can never be remembered for the session; writes inside .git/ always ask.

Memory

The assistant keeps notes across sessions in ~/.config/glbgpt/memory/ — a project folder per workspace and a global folder about you. Each folder's MEMORY.md is a short index loaded at the start of every chat (first 200 lines / 25 KB); other notes are read on demand. Ask it to remember or forget something, or let it save what is clearly worth keeping.

glbgpt memory show            # notes and indexes for this folder (and global)
glbgpt memory show testing.md # print one note (--scope global for global notes)
glbgpt memory path            # folders, to open in an editor
glbgpt memory dream           # re-read recent sessions here, fix/merge/fill memory (uses chat tokens)
glbgpt memory dream --dry-run # show what it would read, without calling a model
glbgpt memory clear --scope project --yes

/memory shows the same in the chat. Start with --no-memory to run without it. exec leaves memory off unless you pass --memory.

Account

CommandWhat it does
glbgpt login [--no-browser] [--code]Sign in. --no-browser prints the URL; --code pastes a one-time code (headless/SSH).
glbgpt logoutSign out and remove stored credentials.
glbgpt whoamiShow the signed-in account.
glbgpt accountMembership and credit balance.
glbgpt account transactionsRecent spend (authoritative billing).
glbgpt updateUpdate the CLI to the latest version (runs npm i -g for you).

Images and video

CommandWhat it does
glbgpt image "<prompt>"Generate an image (asks before spending).
glbgpt video "<prompt>"Generate a video (asks before spending).

Common flags: -m/--model, --ar 16:9, --res 2K, --seed N, --negative-prompt "...", -i ./ref.png (reference image), --duration N and --audio/--no-audio (video), -o/--out <dir>, --estimate (price only, don't generate), --detach (submit and print the task id without waiting). --seed and --negative-prompt only apply to models that take them (glbgpt model show <model>); elsewhere they are ignored with a note.

Audio and 3D

CommandWhat it does
glbgpt audio "<text>" -m eleven-v4 --voice RachelText-to-speech (saves .mp3 / .wav).
glbgpt audio "<description>" -m eleven-musicMusic.
glbgpt audio voices -m <model> [--query q] [--json]List a speech model's voices (free).
glbgpt 3d "<prompt>" -m tripo-h3.1 [-i ./ref.png]3D model (saves .glb, or the chosen format).

-m is required (glbgpt model list audio|3d). --voice takes a voice name or id; omit it for the model's default voice. Model settings go in --param key=value (repeatable), with the keys and values glbgpt model show <model> lists — e.g. --param duration=30 (eleven-music), --param texture_quality=detailed (tripo-h3.1). -o, --estimate and --detach work as for images. Extra 3D files (when a model returns any) are saved next to the main file.

Models and tasks

CommandWhat it does
glbgpt model list [chat|image|video|audio|3d]List available models.
glbgpt model show <model>Parameters and limits for one model.
glbgpt task listRecent generation tasks.
glbgpt task show last · glbgpt task show <id>A task's status.
glbgpt task wait lastBlock until a task finishes.
glbgpt task download lastDownload a finished result.

exec — non-interactive

One request in, the model's answer out. For scripts and external agents; never opens the TUI.

glbgpt exec "capital of France? one word"     # plain text on stdout
echo "summarize this" | glbgpt exec -         # prompt from stdin
git diff | glbgpt exec "review this diff"      # piped stdin appended as context
glbgpt exec "what is in this image?" -i shot.png
glbgpt exec "extract facts" --json            # one result object
glbgpt exec "say hi" --jsonl                   # streaming events, one JSON per line

Flags: -m/--model, --system <text>, --file <path...>, -i/--image <path|url...>, --output-schema <file> (structured output), --json, --jsonl, -o/--output-last-message <file>, --max-credits <n> (optional media credit cap for this run, default none; 0 disables media). Exit code is 0 on success, non-zero on a usage/auth/turn error.

With a prompt argument, piped stdin is appended as context. If the pipe sends nothing within 3s, exec continues without it and says so on stderr, so an idle inherited pipe (common under agent harnesses) never blocks. Redirect < /dev/null to skip the wait; pass slow output with --file.

On tool-capable models the assistant can also read files under the current directory (read-only), search the web / fetch pages, and generate images/videos: exec waits for in-flight generations before exiting and reports each as a media_result event (--jsonl) or a stderr line. A local wait timeout returns pending. If a status check fails, status_unknown means the remote outcome is unknown. Use glbgpt task show <id> to check either result. A generation that succeeded but could not be downloaded returns not_downloaded. Retry the download with glbgpt task download <id>. The exec exit code still describes the chat turn.

Coding tools are off by default in exec (no one is present to approve): the model sees the tools but every command/write is refused with a message naming the enable flag. Opt in with --allow-write (create/edit files), --allow-bash (shell commands), or --yolo (both):

glbgpt exec "fix the failing test in src/utils.test.ts and run the tests" --allow-write --allow-bash

--auto is the middle ground for unattended runs: file writes are allowed and shell commands run inside the sandbox described above. A command the sandbox blocks is refused (nobody is there to approve running it outside), and the model is told why.

mcp — use from other agents

glbgpt mcp runs a Model Context Protocol server over stdio, so agents like Claude Code, Codex, or Cursor can chat and generate media through your GlobalGPT account. Sign in once with glbgpt login first.

ToolWhat it does
glbgpt_chatOne chat turn: question in, answer out (system prompt, vision, JSON schema, and — on tool-capable models — live web search/fetch supported).
glbgpt_generate_imageGenerate an image; usually returns the finished result (URL + local file) in one call.
glbgpt_generate_videoGenerate a video; returns a task_id to check.
glbgpt_generate_audioSpeech (text-to-speech, with a voice name or id) or music; returns the result or a task_id.
glbgpt_generate_3dA 3D model from a prompt and/or images (.glb by default); returns a task_id to check.
glbgpt_list_voicesThe voices of a speech model (filterable), to pick one for glbgpt_generate_audio.
glbgpt_check_taskCheck a generation task. Waits server-side — the agent can just call it again immediately until done.
glbgpt_list_modelsList available chat/image/video/audio/3d models and what parameters each supports.
glbgpt_accountSigned-in account: email, plan, and remaining credit balance.

Register it:

# Claude Code
claude mcp add glbgpt -- glbgpt mcp

# Codex — add to ~/.codex/config.toml
[mcp_servers.glbgpt]
command = "glbgpt"
args = ["mcp"]

Cursor and other JSON-config clients:

{ "mcpServers": { "glbgpt": { "command": "glbgpt", "args": ["mcp"] } } }

No install (runs via npx — first call downloads the package):

claude mcp add glbgpt -- npx -y -p @glbgpt/cli glbgpt mcp

Codex (~/.codex/config.toml):

[mcp_servers.glbgpt]
command = "npx"
args = ["-y", "-p", "@glbgpt/cli", "glbgpt", "mcp"]

Generic JSON config:

{ "mcpServers": { "glbgpt": { "command": "npx", "args": ["-y", "-p", "@glbgpt/cli", "glbgpt", "mcp"] } } }

Sign in once with npx -y -p @glbgpt/cli glbgpt login (or set GLBGPT_TOKEN).

Spending control. Media generation spends real credits from your account; by default there is no per-session cap (your balance is the limit). To set one, use glbgpt mcp --max-credits <n> in the client config ("args": ["mcp", "--max-credits", "8000"]), persistently via glbgpt config set max-credits <n>, or --max-credits 0 to disable media generation entirely. When a cap would be exceeded the tool refuses and tells the agent how to ask you to raise it — nothing is charged.

Generated files are saved under glbgpt-output/ in the directory the server was started in (usually your project directory), alongside the hosted URL.

skill — teach agents to drive the CLI

glbgpt skill install drops four bundled Agent Skills into the directories coding agents read: globalgpt (the all-in-one entry — /globalgpt for a menu of everything plus balance, spend, and task queries), globalgpt-image and globalgpt-video (say "make me an image/video" — or invoke /globalgpt-image bare to pick a model from a live menu first) and globalgpt-coding (/globalgpt-coding: delegate a code subtask to a GlobalGPT chat model you choose; the delegate reads code via the CLI, so delegated content is sent to GlobalGPT).

glbgpt skill install          # symlinks into ~/.claude/skills and ~/.agents/skills
glbgpt skill install --copy   # copy instead of symlink

Symlinks are the default, so updating the CLI updates the skill content automatically. To update: npm i -g @glbgpt/cli && glbgpt skill install — the reinstall is idempotent and picks up newly added skills (and cleans up retired ones). Restart your agent afterwards. Re-running --copy overwrites whatever is in the installed directory — any edits you made to a copied skill are lost — while the symlink default just re-points the link and leaves nothing to lose.

Which surface should you use?

Use it when
SkillYour agent runs shell commands (Claude Code, Cursor, Codex). Zero config — install once and ask for an image.
MCPYour agent speaks MCP but cannot run shell commands, or you want the session credit budget enforced (--max-credits).
CLI / execYou are scripting it yourself, in CI, or piping output between tools.

config

CommandWhat it does
glbgpt config listShow persisted settings.
glbgpt config get <key> · set <key> <value> · unset <key>Manage settings.

Keys: lang, max-credits (unattended media budget), max-tool-calls (tool calls per chat turn, default 100), max-turn-tokens (cumulative request tokens per turn, default 500000), context-pruning (set false to keep old tool results in long chats), update-check (set false to disable the startup update prompt and notices about newer versions). One-shot overrides via env vars (GLBGPT_LANG, GLBGPT_TOKEN, GLBGPT_MAX_CREDITS, GLBGPT_MAX_TOOL_CALLS, GLBGPT_MAX_TURN_TOKENS, GLBGPT_CONTEXT_PRUNING, GLBGPT_UPDATE_CHECK) always win.

For very long coding tasks, use glbgpt config set max-tool-calls 300 or set GLBGPT_MAX_TOOL_CALLS=300 for one run. Values must be integers from 0 to 1000; 0 disables tool calls. This counts all dispatched tools in a chat turn and is not a token or credit limit: raising it can increase model usage and cost. When the budget is reached, the CLI preserves completed work in the conversation and requests a final answer with no further tool execution, including any remaining work, if the token budget permits. The turn is marked paused. Send a follow-up message to continue with a new turn's budget.

Conversation spending protection is separate from the media credit budget. Set glbgpt config set max-turn-tokens 100000 or GLBGPT_MAX_TURN_TOKENS=100000 for a smaller allowance (integers from 1000 to 10000000). All model requests in one turn count, including tool rounds, safe structured-output retries, and automatic context compaction. At 80% the CLI warns; before each request it compares the estimated input with the remaining budget. It pauses without another summary request when the budget is exhausted or the next input would exceed it. Provider usage is used when available; missing values are estimated and marked ~ in the turn counter. Image attachments use a per-image reserve (4096 tokens for explicit low detail, otherwise 16384), independent of URL/base64 transport size; actual image token usage varies by model. An in-flight response, hidden reasoning, server prompts, and different tokenizers can exceed the estimate: this is not a hard billing cap or an exact credit estimate. The footer labels session totals separately from the current turn budget. glbgpt account transactions remains the billing source.

Repeated unchanged tool results warn on the third occurrence and pause on the fifth. Repeated Python failures can also be detected when the inline script changes but the same command target returns the same error. Changed output or a new successful file mutation resets the corresponding evidence; running background-task polling is exempt. These are conservative local observations, not proof that a model is in an infinite loop or that a task is too complex. On pause, the CLI preserves work and history, shows the reason, and waits for a new message; queued messages do not automatically restart it. On resume, older queued text appears before your newest instruction in the model history. Starting a new session clears held messages and pending attachments.

A normal answer ends a conversational turn; it does not certify a finished coding task. For clearly named file creation requests, the CLI checks that the requested files exist and are nonempty, without executing them. Missing/empty files are marked incomplete; existing files remain unverified for correctness. Ambiguous output descriptions are not inferred. Reference files and appended stdin context are excluded from this check. If a later message steers the active turn, the original inferred check is skipped because its targets may no longer apply. The model is instructed to implement action requests, verify when possible, and explain tests performed and unfinished work. There is no automatic paid follow-up just because a model stopped with a plan. Request errors remain errors, with the upstream message when available, rather than being labeled a loop. One exception: when the server rate-limits requests (60 a minute per account, shared by every session you have running), the CLI waits the time the server asks for and continues the turn — up to three times per turn.

exec --jsonl emits additive notice, task_status, and turn_paused events. A paused turn exits nonzero; JSON errors include a reason (repeated_no_progress, token_budget, tool_budget, or tools_unavailable) and status: "paused". Partial text and known usage are retained. A missing deliverable also exits nonzero and has task.status: "incomplete"; a normal response without a file check keeps the existing result format.

Context pruning also runs between tool rounds, preserving the raw history on disk. exec and MCP usage totals include every model request in the turn; these token counts are not a credit charge estimate.

Notes

Updates. When a newer version exists, an interactive start shows a chooser (Enter updates on the spot; "Skip until next version" mutes the chooser for that release), and exec/MCP print a one-line notice on stderr so agent hosts can relay it. The check reads a local cache refreshed in the background — it never blocks startup or touches the network on the hot path. glbgpt update upgrades any time; update-check false disables it all.

Usage telemetry. The CLI reports account-linked usage events (session starts, turn latency, tool-call counts, error categories) to the GlobalGPT backend to help us improve the product. It never collects prompt text, file contents, or file paths. Set GLBGPT_DISABLE_TELEMETRY=1 to turn it off entirely.

Credentials are stored at ~/.config/glbgpt/credentials.json (dir 0700, file 0600). The token is long-lived; on a 401 the CLI asks you to glbgpt login again. Please report anything that looks wrong.

Development

See the maintenance guide for the source map, local checks and historical-document policy, and the release guide for the test-to-production workflow.

版本与发布记录

@glbgpt/cli 共发布 53 个版本,首次发布于 2026/07/16;过去 12 个月发布了 53 个版本。

版本发布日期距今
0.2.34latest2026/11/16今天
0.2.332026/11/151 天前
0.2.322026/11/133 天前
0.2.312026/11/133 天前
0.2.302026/11/133 天前
0.2.292026/11/133 天前

其他发布通道:test → 0.1.3。

关于 @glbgpt/cli 的常见问题

@glbgpt/cli 是什么?

GlobalGPT in your terminal — chat, image and video generation, and an exec entry point for scripts and agents.

如何安装 @glbgpt/cli?

在项目目录运行 npm install @glbgpt/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 glbgpt、globalgpt,可以用 npx glbgpt 直接运行。

@glbgpt/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/glbgpt__cli 是否存在。

@glbgpt/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@glbgpt/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@glbgpt/cli 可以商用吗?

@glbgpt/cli 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@glbgpt/cli 的下载量有多少?

根据 npm 官方下载统计,@glbgpt/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,659 次,日均约 189 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glbgpt/cli 还在维护吗?

最新版本 0.2.34 发布于 2026/11/16(今天);至今共发布 53 个版本,其中过去 12 个月发布了 53 个;首次发布于 2026/07/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。