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
| Command | What it does |
|---|---|
glbgpt | Start 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>:
| Mode | Behavior |
|---|---|
default | Ask before every command and file write. |
accept-edits | File writes run without asking; commands still ask. |
auto | File writes and shell commands run without asking; commands run in a sandbox. |
yolo | Nothing 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
| Command | What it does |
|---|---|
glbgpt login [--no-browser] [--code] | Sign in. --no-browser prints the URL; --code pastes a one-time code (headless/SSH). |
glbgpt logout | Sign out and remove stored credentials. |
glbgpt whoami | Show the signed-in account. |
glbgpt account | Membership and credit balance. |
glbgpt account transactions | Recent spend (authoritative billing). |
glbgpt update | Update the CLI to the latest version (runs npm i -g for you). |
Images and video
| Command | What 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
| Command | What it does |
|---|---|
glbgpt audio "<text>" -m eleven-v4 --voice Rachel | Text-to-speech (saves .mp3 / .wav). |
glbgpt audio "<description>" -m eleven-music | Music. |
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
| Command | What 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 list | Recent generation tasks. |
glbgpt task show last · glbgpt task show <id> | A task's status. |
glbgpt task wait last | Block until a task finishes. |
glbgpt task download last | Download 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.
| Tool | What it does |
|---|---|
glbgpt_chat | One chat turn: question in, answer out (system prompt, vision, JSON schema, and — on tool-capable models — live web search/fetch supported). |
glbgpt_generate_image | Generate an image; usually returns the finished result (URL + local file) in one call. |
glbgpt_generate_video | Generate a video; returns a task_id to check. |
glbgpt_generate_audio | Speech (text-to-speech, with a voice name or id) or music; returns the result or a task_id. |
glbgpt_generate_3d | A 3D model from a prompt and/or images (.glb by default); returns a task_id to check. |
glbgpt_list_voices | The voices of a speech model (filterable), to pick one for glbgpt_generate_audio. |
glbgpt_check_task | Check a generation task. Waits server-side — the agent can just call it again immediately until done. |
glbgpt_list_models | List available chat/image/video/audio/3d models and what parameters each supports. |
glbgpt_account | Signed-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 | |
|---|---|
| Skill | Your agent runs shell commands (Claude Code, Cursor, Codex). Zero config — install once and ask for an image. |
| MCP | Your agent speaks MCP but cannot run shell commands, or you want the session credit budget enforced (--max-credits). |
| CLI / exec | You are scripting it yourself, in CI, or piping output between tools. |
config
| Command | What it does |
|---|---|
glbgpt config list | Show 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.