Documentation

OnlyCLI is a BYOK AI agent for the terminal. It edits files behind a diff-approval gate, searches the web, and drives Roblox Studio and Godot 4 over MCP.

Install

Node.js 18.17 or newer is required.

npm install -g onlycli
onlycli --version

From source:

npm install
npm run build
npm link          # makes `onlycli` available everywhere

npm link points at dist/, so re-run npm run build after changes; npm unlink -g onlycli removes it. If the command is not found, restart the terminal — PATH changes do not reach already-open sessions. During development you can skip the build with npm run dev or npm run dev -- agent "...".

Quick start

# 1. Store a key (entered as hidden input)
onlycli auth add --provider anthropic

# 2. Interactive chat
onlycli

# 3. Or a one-off request
onlycli agent "find the off-by-one error in this function" -f src/utils.ts

Providers

--base-url and /baseurl apply only to openai; the Anthropic and Google SDKs use fixed endpoints. An http:// endpoint produces a warning, because the key would travel in clear text.

CLI commands

Shared flags

These work on both chat and agent:

agent also accepts --image <path> and --clipboard to attach an image. Unquoted prompts are joined rather than truncated, so onlycli agent add a jump animation sends the whole sentence.

Slash commands

Inside chat, a line starting with / is handled locally and never sent to the model. To send literal text that begins with /, start the line with //.

Saved preferences

Session settings you change with a slash command are remembered on your own machine, in ~/.onlycli/config.json. Nothing about them is sent to a server. The persisted settings are:

Precedence on startup is: flag for this run > saved preference > built-in default. So --yes or --no-web stays one-shot and does not rewrite what you chose earlier, while /auto on inside chat does persist. The model is remembered per provider, so switching back to a provider restores the model you last used with it rather than a global value that may not exist there.

Delete ~/.onlycli/config.json to reset every preference. API keys are not in that file — see key storage.

Approval and /auto

By default every file write is shown as a diff and waits for your answer; press d to see the full diff before deciding. /auto on (or --yes) applies changes immediately — convenient for a long build-out session, risky on a codebase you do not know.

Web access

The agent can search and read pages by default; --no-web or /web off turns it off. No key is needed — the keyless DuckDuckGo path is used. That path scrapes HTML and is rate-limited, so adding a Brave or Tavily key (onlycli auth search add, or BRAVE_API_KEY / TAVILY_API_KEY) gives more reliable results.

How MCP works here

/mcp <engine> launches that engine's MCP server as a child process and talks to it over stdio. On connect, the server's tool list is described to the model; when the model wants one, it emits a tool block, OnlyCLI executes the call and returns the result as the next turn's input.

/mcp list            # engines and status
/mcp roblox-studio   # requires Roblox Studio to be open
/mcp godot           # requires Godot 4 and npx
/mcp status          # what is connected, how many tools
/mcp disconnect

Roblox Studio

1. Open Roblox Studio (a recent version, which ships the MCP server).
2. Open the Assistant panel → ... ⟩ Manage MCP Servers → enable "Enable Studio as MCP server".
3. Run /mcp roblox-studio in chat.

No plugin and no manual token. Script paths are instance paths with no file extension. StarterPlayerScripts and StarterCharacterScripts are children of StarterPlayer, not services, so write the full path: StarterPlayer/StarterPlayerScripts/Movement.

Godot 4

Godot support runs the community godot-mcp server through npx, pinned to a known version so an upstream release cannot silently change the tool surface. The first connection downloads it.

The Godot binary is resolved in this order: GODOT_PATH, then PATH, then common install and download folders — Desktop, Downloads, %LOCALAPPDATA%\Programs, Program Files\Godot, the Steam library, C:\Godot, plus the usual Unix locations and Godot.app. Among several candidates the highest version wins, then the most stable channel, then the non-console build (the _console variant opens an extra terminal window).

# Windows
setx GODOT_PATH "C:\path\to\Godot_v4.4-stable_win64.exe"

# macOS / Linux
export GODOT_PATH=/path/to/godot

Godot tools (14)

Godot limitations worth planning around

Unity and Unreal appear in /mcp list but are not implemented yet.

Key storage

Keys are looked up in this order:

1. Environment variable — ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY. Overrides everything. Best for CI.
2. OS keychain — via the optional @napi-rs/keyring dependency (Keychain, Credential Manager, Secret Service). Primary storage when installed.
3. ~/.onlycli/credentials.json — fallback, written with 0600.

The file fallback stores keys as plain text and the CLI warns when it is used. Encrypting it with a key kept on the same machine would add no real protection, so that is deliberately not done; use an environment variable if you want stronger isolation. onlycli auth list masks keys and a full value is never printed.

Environment variables

Security behavior

• Files that may hold secrets (.env, credentials.json, *.pem, *.key, .npmrc) are neither added to context nor writable by the agent.
• Agent file paths resolve inside the working directory; ../ and escaping absolute paths are rejected. Your own /cd navigation is unrestricted — the limit is on the agent's authority, not on you.
• No file is written without approval unless you opt out with /auto or --yes.
• Web text reaches the model as untrusted data inside an explicitly delimited block; instruction-shaped sentences in it are not obeyed. That is a mitigation, not a guarantee — review diffs when the agent has been reading foreign content.
• Page fetching allows only http/https and rejects localhost, private ranges (10.x, 192.168.x, 172.16–31.x), link-local 169.254.x (cloud metadata), and single-label hostnames. Addresses are re-checked after each redirect, so a redirect cannot walk into the internal network (SSRF).
• URLs with embedded credentials (user:pass@host) are rejected. Response size and request time are capped; non-text responses are not downloaded.

Troubleshooting