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.