CLI & SDK Reference
Proxima includes a terminal command-line tool (CLI), an OpenAI-compatible local REST
server, streaming WebSockets, and developer SDK libraries. This page describes Proxima v5.5.0.
Everything here talks to the same local gateway, so the Proxima desktop app must be running and
the REST API must be enabled in Settings.
1. CLI Command Reference
The proxima CLI lets you query providers, run debugging corrections, and
format outputs directly from your shell.
Primary Operations
# General chat (provider optional)
proxima ask "Explain concurrency in Go"
proxima ask claude "Review my logic"
proxima ask gemini "Compare these two designs" --thinking high
# Ask every active provider and compare side by side
proxima compare "Bun vs Node.js"
# Coding tools: generate (default) | review | explain | debug
proxima code review "def fib(n): ..." --lang python
# Fix an error from text or a file
proxima fix "SyntaxError: Unexpected token"
proxima fix --file error_trace.log
Other Commands
proxima search "latest Node.js release" # web search through Perplexity
proxima debate "tabs vs spaces" # multi-AI debate
proxima audit "SELECT * FROM users WHERE id=" # security scan of code
proxima translate "Hello world" --to Hindi # --from sets the source language
proxima analyze "https://example.com" -q "what is this?"
proxima brainstorm "dev productivity features"
proxima models # live models and status
proxima status # gateway health and bound port
proxima stats # latency metrics
proxima new claude # reset one provider's conversation
Flags
--model, -m <name> Override provider or a specific engine (for example gemini:pro)
--thinking <level> default | low | medium | high (new in 5.5.0)
--file <path> Add a local file. Text is appended to the prompt;
images and PDFs are uploaded natively.
--lang, -l <lang> Target language for code generation
--to / --from Target and source language for translate
--json Print the raw JSON response, for scripting
Finding the gateway port
The CLI first checks PROXIMA_REST_PORT or PROXIMA_PORT, then
reads rest-port.json from Proxima's user data folder
(%APPDATA%\Proxima on Windows, ~/Library/Application Support/Proxima on
macOS, ~/.config/Proxima on Linux), and finally falls back to 3210.
PROXIMA_HOST changes the host (default 127.0.0.1). Run
proxima status to see which port it connected to.
Terminal Piping Support
Forward execution errors, logs, or git differences straight into the command parser:
# Pipeline build issues
npm run build 2>&1 | proxima fix
# Pipeline codebase reviews
git diff | proxima code review
2. REST API & WebSocket Specifications
The desktop app runs an OpenAI-compatible REST server locally, by default at
http://localhost:3210. If that port is taken, Proxima tries the next free ports and
records the one it bound in rest-port.json; GET /api/status also reports
it. Set PROXIMA_REST_PORT to start from a different port.
REST Endpoints
POST /v1/chat/completions OpenAI-style completions (streams, tool requests, thinking controls)
POST /v1/cancel Cancel in-flight generation and flush the provider queue
GET /v1/models List live, discovered models (session and BYOK)
GET /v1/functions Function catalog
GET /v1/stats Latency and response stats
POST /v1/conversations/new Reset a provider's conversation
GET /api/status Server status, bound port and providers
Thinking depth and cancellation
# Reasoning depth: default | low | medium | high (or OpenAI "reasoning_effort")
curl http://localhost:3210/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "gemini", "message": "Check this complexity claim", "thinking_level": "high"}'
# Cancel the running request (provider is optional)
curl -X POST http://localhost:3210/v1/cancel \
-H "Content-Type: application/json" \
-d '{"provider": "gemini"}'
Contradictory or unsupported thinking_level / reasoning_effort
values are rejected with HTTP 400.
WebSocket Stream (ws://localhost:3210/ws)
Establishes a real-time connection for streamed tokens and status events. It runs on the
same port as the REST API:
const ws = new WebSocket("ws://localhost:3210/ws");
ws.onopen = () => {
ws.send(JSON.stringify({
action: "ask",
model: "gemini",
thinking_level: "high",
message: "Explain closures in JavaScript",
id: "req-1"
}));
};
ws.onmessage = (e) => {
const msg = JSON.parse(e.data);
console.log(msg); // streamed chunks, status events, or completion
};
3. Developer SDKs
Both SDKs wrap the REST gateway. They find the right port through
rest-port.json, retry transient network errors, and accept
thinking_level and reasoning_effort on chat calls.
Python SDK
from proxima import Proxima
client = Proxima()
res = client.chat(
"Hello",
model="claude"
)
print(res.text)
deep = client.chat(
"Review this design",
model="gemini",
thinking_level="high"
)
print(client.get_models())
JavaScript SDK (ESM and CommonJS)
import { Proxima } from 'proxima-sdk';
// or: const { Proxima } = require('proxima-sdk');
const client = new Proxima();
const res = await client.chat("Hello", {
model: "claude"
});
console.log(res.text);
const deep = await client.chat("Review this design", {
model: "gemini",
thinking_level: "high"
});
console.log(await client.getModels());
Setup
- Python: copy
sdk/proxima.py from the repository into your project. It needs the requests package.
- JavaScript: from a clone of the repository run
npm install ./sdk. The package ships a native ES module entry (proxima.mjs) next to the CommonJS file, so import and require both work. It needs Node.js 18 or newer.
Methods
chat(message, model, thinking_level, reasoning_effort) Send a prompt; returns an object with .text, .model, .provider
getModels() / get_models() Live models discovered for your accounts and BYOK providers
getFunctions() / get_functions() Gateway function catalog
getStats() / get_stats() Per-provider performance and latency
newConversation(provider) / new_conversation(provider) Reset a provider's conversation
Model names: instead of hard-coding model names, call
getModels() (or
get_models()) and use the slugs it returns, for example
gemini:pro or a ChatGPT slug from your account. Models differ per account, and
since 5.5.0 requesting an unavailable one returns an error instead of a silent substitute.
See
What's new in 5.5.0.