node-gpt-cli-debian

Simple OpenAI ChatGPT CLI in Node.js for Debian, Windows, and WSL.

This README was generated by GPT-5 and may be inaccurate.

• Core script: gpt.js
• CLI shims: cli/gpt (bash), cli/gpt.cmd (Windows)
• Installers: installer/install.sh, installer/install.cmd

Features

• One-shot prompts or interactive REPL
• File input (--in) and file output (--out)
• Session history persisted to JSON (--session), auto-detected .gptp files in CWD
• Optional system role (--role) and dev-mode output (--dev)
• Streaming tokens by default (disable with --no-stream)
• Model/temperature/max-tokens controls
• LM Studio model routing via lms: model prefix
• Toggleable two-pass fallback reasoning for non-reasoning models (reasoning request + answer request)
• Interactive tool-calling with local file/shell helpers, web search, and direct URL content fetching
• Tool-calling can be disabled globally via CLI flag or toggled during chat

Backed by the official OpenAI SDK via the chat completions API in gpt.js.

Requirements

• Node.js 18+ and npm
• An OpenAI API key available as the OPENAI_API_KEY environment variable

Auto-install on Debian/Ubuntu/WSL

Auto-install prerequisites and this CLI in one step using either command:

wget -qO- https://raw.githubusercontent.com/TheCyaniteProject/debian-automations/main/full-install.sh | bash

or

curl -fsSL https://raw.githubusercontent.com/TheCyaniteProject/debian-automations/main/full-install.sh | bash

Install on Debian (manual)

1. Install Node.js

• Debian/Ubuntu:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

or

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

nvm install --lts
nvm use --lts

1. Run the installer from the project directory

cd node-gpt-cli-debian
chmod +x installer/install.sh
./installer/install.sh

What the installer does:

• Runs npm install in the project root
• Adds the cli directory to your PATH (system-wide via /etc/profile.d if run with sudo; otherwise in your shell profile)
• Optionally saves OPENAI_API_KEY to your profile
• Optionally sets LM_STUDIO_BASE_URL using a custom LM Studio port

Non-interactive API key setup:

./installer/install.sh --api-key "sk-XXXX"   # or --api-key=sk-XXXX

Non-interactive LM Studio port setup:

./installer/install.sh --lms-port 1234   # or --lms-port=1234

Notes:

• Use -y (or SKIP_API_PROMPT=1) to skip the API key prompt entirely.
• --api-key sets and persists OPENAI_API_KEY without prompting.
• --lms-port sets and persists LM_STUDIO_BASE_URL as http://127.0.0.1:<port>/v1.

3. Reload your shell

exec "$SHELL"

Now gpt should be available in your PATH.

Install on Windows (Command Prompt or PowerShell)

Requirements:

• NVM for Windows (recommended). Install from https://github.com/coreybutler/nvm-windows/releases, then run:

nvm install --lts
nvm use --lts

Steps:

cd node-gpt-cli-debian
installer\install.cmd

What the installer does:

• Runs npm install in the project root
• Adds the cli directory to your user PATH via setx (no admin needed)
• Optionally saves OPENAI_API_KEY to your user environment
• Optionally sets LM_STUDIO_BASE_URL from a custom LM Studio port

Notes:

• Open a NEW terminal window after installation so the updated PATH and variables apply.
• Test with: gpt --interactive

To skip the API key prompt:

installer\install.cmd -y

To set LM Studio port non-interactively:

installer\install.cmd --lms-port 1234

If you prefer manual PATH setup, add the absolute path to the cli folder to your user PATH.

Install on WSL (Ubuntu/Debian)

Run the Linux installer inside WSL. This makes gpt available in your WSL shell.

cd node-gpt-cli-debian
chmod +x installer/install.sh
./installer/install.sh
exec "$SHELL"

API key in WSL:

• Set it in WSL just like Linux: export OPENAI_API_KEY="sk-..." and persist in ~/.profile.
• Windows environment variables are not automatically imported into WSL shells. If your key is set in Windows, copy it into WSL and export it there.

You can also set it non-interactively during install:

./installer/install.sh --api-key "sk-XXXX"

Configure your API key

You can set it during installation, or later:

export OPENAI_API_KEY="sk-..."

To persist it:

• Add the export line to ~/.profile (or ~/.bash_profile), or rerun the installer to append it for you.
• Or pass it directly to the installer: ./installer/install.sh --api-key "sk-XXXX".

Quick start

One-shot prompt:

gpt "Write a haiku about Debian"

Interactive REPL:

gpt --interactive

With a system role and session file:

gpt --role "You are a helpful CLI assistant." --session myproj "Summarize src"

Usage

All options are implemented in gpt.js:

gpt [prompt]

Options:
  -i, --in <filepath>         Input file to prepend to the prompt
  -o, --out <filepath>        Write the assistant reply to a file (also prints unless --quiet)
  -r, --role <message>        Add a system message before the first user prompt
  -d, --dev                   Developer mode: ask for code-only output; strips code fences
  -m, --model <id>            Model ID (default: gpt-4.1-mini)
      --reasoning <trueOrFalse>
              Enable fallback reasoning layer for non-reasoning models
      --show-reasoning <trueOrFalse>
              Ask model to include visible reasoning before final answer
      --tools <on/off>
              Enable or disable tool-calling in interactive chat
      --set-default-reasoning <trueOrFalse>
              Save default reasoning mode to config (true/false)
  -t, --temperature <number>  Sampling temperature (0–2)
      --max-tokens <number>   Maximum output tokens
  -q, --quiet                 Do not print response to stdout
  -s, --session <project>     Persist chat history to <project>.gptp (JSON). Auto-detects a single .gptp in CWD
  -I, --interactive           Start interactive chat REPL
      --no-stream             Disable streaming (non-streaming by default when --dev)

Notes:

• Streaming is on by default, except when --dev is used (to keep outputs clean for scripting).
• If --session is omitted, the CLI will auto-load the most recent .gptp file in the current directory if exactly one exists.
• Use lms:<modelName> to route requests to LM Studio's OpenAI-compatible server (default base URL: http://127.0.0.1:1234/v1).
• Override LM Studio base URL with LM_STUDIO_BASE_URL and optional API key with LM_STUDIO_API_KEY.

Examples

• Pipe a file into the prompt context and save the answer:

gpt -i README.md -o answer.txt "Extract the key points"

• Non-streaming with specific model and temperature:

gpt --no-stream -m gpt-4.1-mini -t 0.2 "Write a release note"

• Use an LM Studio model (CLI and interactive /model set both support this format):

gpt -m lms:gemma-3 "Summarize this file"

• Enable fallback reasoning for a one-shot request (only active on non-reasoning models):

gpt --reasoning true -m gpt-4.1-mini "Compare two approaches and recommend one"

• Ask for visible reasoning (printed before final answer) on demand:

gpt --show-reasoning true -m gpt-4.1-mini "How should I refactor this module?"

• Persist fallback reasoning as the default:

gpt --set-default-reasoning true

Interactive toggle:

• In REPL mode, run /model showreasoning on (or off) to enable/disable visible reasoning for subsequent replies.
• In REPL mode, run /model tools on (or off) to enable/disable tool-calling.

Disable tools from the CLI start:

gpt --interactive --tools off

• Interactive session with persistent history:

gpt -I -s demo

How it works

The CLI wraps the OpenAI SDK (see package.json) and auto-detects whether a model should use Chat Completions (/v1/chat/completions), legacy Completions (/v1/completions), or Responses (/v1/responses). It builds chat messages from your inputs and session history, and converts that history into a text prompt for non-chat endpoints when needed. See the main logic in gpt.js.

Entry points:

• POSIX shell shim: cli/gpt
• Windows shim: cli/gpt.cmd

Installers:

• Debian/Linux: installer/install.sh (adds cli to PATH and optionally configures OPENAI_API_KEY)
• Windows: installer/install.cmd

Troubleshooting

• Command not found: ensure your shell has reloaded after installation (exec "$SHELL"), and confirm which gpt points to the repo's cli/gpt.
• Auth errors: confirm OPENAI_API_KEY is exported in the current shell: env | grep OPENAI_API_KEY.
• Old Node.js: ensure Node 18+ (node -v).
• Windows PATH not updated: open a NEW Command Prompt/PowerShell window after running installer\\install.cmd. Verify with where gpt.
• WSL cannot see Windows variables: export OPENAI_API_KEY inside WSL and persist in ~/.profile.

License

ISC (see package.json).