saintz-setup

Connect your coding tools to Saintz. In a terminal it walks you through it: your key (checked first), the tools it finds, the models, and a menu to manage it all afterwards. Every tool is pointed at https://api.saintz.my. English and Bahasa Melayu. No dependencies, Node 18 or newer. Nothing to install first:

npx saintz-setup                       # in a terminal: the guided screens (first run: language, key, tools; after that: a menu)
npx saintz-setup codex                 # one tool, no questions: claude-code | codex | opencode | hermes | env
npx saintz-setup doctor                # check this computer, the key and each tool; says what to do about a problem
npx saintz-setup check                 # test your key against the API, route by route
npx saintz-setup list                  # what is installed, what is set up
npx saintz-setup auth [show|revoke|reload [tool]]   # save a new key, show it masked, remove it everywhere, refresh copies
npx saintz-setup lang [show|set en|ms] # English or Bahasa Melayu
npx saintz-setup enter [screen]        # open one screen: main, tools, claude-code, codex, opencode, hermes, models, key, language, doctor, undo
npx saintz-setup init                  # run the first-run screens again
npx saintz-setup undo [tool|all]       # take back what it wrote
npx saintz-setup other                 # Cursor, Continue, Cline, Claude Desktop (settings screens)

(Or install it once with npm install -g saintz-setup and drop the npx.)

Get a key in the Saintz app: Settings > Developer > API keys. Give it when asked (nothing is shown as you type: only dots and a count), or set SAINTZ_API_KEY, or pipe it in with --key-stdin. Avoid --key: it shows in your shell history and the process list.

The screens

Arrow keys (or j/k, or a number) move, Enter chooses, Esc or Backspace goes back, Space ticks, Ctrl-C leaves at any time and leaves your terminal as it was. They open only when both your input and your output are a terminal: in a script, a pipe, or with --yes, --dry-run, --print, --key or --key-stdin, nothing is asked and the plain command runs.

• First run: language, key (checked live; a wrong one can be retried), which tools to set up, then it sets them up and starts the real tool to confirm each one loads what was written.
• Every run after: a menu. Per tool: set up again, view the setup (the key is shown masked), choose models, start it, remove only that tool. Also: the key, the language, doctor, and undo.
• A tool that is not installed can be installed for you, but only after the exact command is shown and you say yes: npm install -g @anthropic-ai/claude-code, @openai/codex or opencode-ai, and nothing else. Hermes is never installed for you; you get instructions.

NO_COLOR turns colour off, and a terminal without UTF-8 gets plain ASCII symbols.

What it does to your computer

Your normal setup is not changed. Each tool gets its own launcher, and your own login, config and defaults stay as they are:

| Tool | What is written | Start it with | |---|---|---| | Claude Code | launcher saintz-claude (sets ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, the main model and the three tier models) | saintz-claude | | Codex | ~/.codex/saintz.config.toml and launcher saintz-codex | saintz-codex (= codex --profile saintz) | | OpenCode | ~/.saintz/gateway/opencode.json and launcher saintz-opencode | saintz-opencode | | Hermes | a saintz provider through Hermes's own hermes config set, the key in Hermes's .env, and hermes tools disable skills | hermes chat --provider saintz --model claude-sonnet-5 |

The key is saved once in ~/.saintz/gateway/key (only you can read it). The launchers read it when they run, so it is never on a command line, in your shell history, or in a config you might paste into a chat. Hermes is the exception: it only reads its own .env. auth revoke removes the saved key and every copy this tool wrote (Hermes's .env, a --global Claude Code token) and puts your own values back; to stop the key working anywhere, delete it in the app. auth --no-validate saves a key without testing it, for when you are offline.

--global also changes the tool's own settings (Claude Code settings.json, OpenCode's global config); --default makes Saintz the default provider. Both are off unless you ask, and setting a tool up again from the screens keeps whichever you used. --dry-run shows what would be written and writes nothing. Before an existing file is changed it is copied to ~/.saintz/gateway/backups/, and undo puts everything back (Hermes settings included). Everything this tool keeps for itself is under ~/.saintz/gateway/: the key, a small settings.json (language and the models you chose; never a secret), a logs/ folder (what was done, never a key: any key is masked, and files older than 14 days are deleted), the backups and the list of changes. undo all removes all of it. The Saintz Code CLI's own folder, ~/.saintz/code/, is never touched.

Which models work where

• Claude Code and Hermes: Claude models. Claude Code asks for models by tier (haiku, sonnet, opus); the launcher sets each tier from your key's own list, the newest of each family, and a tier with no match falls back to a model your key does have.
• Codex: GPT models, over the Responses API.
• OpenCode: GPT models, over the Messages API (tool calls work). Claude models are not offered for OpenCode.
• A key that lists no GPT models gets Claude Code and Hermes only; Codex and OpenCode say why they were skipped.
• The Models screen chooses a main and a small model for each family (default, from your key's list, or a typed id). The choice is kept in settings.json and used the next time a tool is set up; if your key stops listing a model, it is ignored rather than written.

saintz-setup check shows which models your key can use and sends one tiny request through each route (Messages, chat completions and, if you have GPT, Responses). saintz-setup doctor goes further: Node, your PATH, the key file's permissions, the key and the network with a real call, Git for Windows (Claude Code needs it there), and for each tool whether it is installed, set up, and really loads its setup. Every problem comes with the next step, and the exit code is 1 if anything failed.

Troubleshooting

• "The key was not accepted": copy it again from the app, or make a new one. Keys start with ccw_live_.
• "Timed out": check your network, VPN or proxy. Node 24 and newer can use HTTPS_PROXY when NODE_USE_ENV_PROXY=1.
• "not on your PATH": the launchers live in ~/.local/bin if that is on your PATH, otherwise in ~/.saintz/gateway/bin; the tool prints the one line that adds it.
• Something does not work and you do not know why: npx saintz-setup doctor.
• Another address (a test server): --base-url https://....