Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

cli: publish freellmapi to npm (#671) (#672)

Tashfeen36eea7bba58b
diff --git a/.github/workflows/cli-release.yml b/.github/workflows/cli-release.yml
new file mode 100644
index 00000000..db101634
--- /dev/null
+++ b/.github/workflows/cli-release.yml
@@ -0,0 +1,116 @@
+name: CLI release
+
+# Publishes the `freellmapi` CLI to npm. Closes #671 — the README and
+# docs/clients.md have always documented `npx freellmapi setup-claude`, but the
+# package was never pushed to the registry, so every one of those commands died
+# with npm E404.
+#
+# Triggers:
+# - push to main touching cli/** publish when cli/package.json's version is
+# not on the registry yet; no-op otherwise
+# - workflow_dispatch manual run
+#
+# The version guard makes this idempotent: ordinary cli/src changes re-run the
+# job, see the version already published, and skip. To ship a new version, bump
+# `version` in cli/package.json in the PR that changes the code.
+#
+# Auth is npm trusted publishing (OIDC) — no NPM_TOKEN, no long-lived secret.
+# npm revoked all classic tokens in December 2025, and granular tokens with
+# "bypass 2FA" are being wound down through 2026 (they lose direct publish
+# around January 2027), so a token-based workflow would have been born
+# deprecated. OIDC mints a short-lived credential per job instead, and npm
+# attaches provenance automatically.
+#
+# One-time setup on npmjs.com (Package settings → Trusted Publisher):
+# Organization or user: tashfeenahmed
+# Repository: freellmapi
+# Workflow filename: cli-release.yml
+# Trusted publishing cannot bootstrap a package that does not exist yet — npm
+# has no package settings page to configure until the first version is up — so
+# 0.3.0 was published manually. Every version after it goes through here.
+#
+# Requires npm >= 11.5.1 and Node >= 22.14.0 for OIDC, hence Node 24 below
+# (still inside the repo's engines range of >=20.18 <25).
+
+on:
+ workflow_dispatch:
+ push:
+ branches: [main]
+ paths:
+ - 'cli/**'
+ - '.github/workflows/cli-release.yml'
+
+permissions:
+ contents: read
+ id-token: write # OIDC credential for trusted publishing
+
+jobs:
+ publish:
+ name: Publish to npm
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '24'
+ registry-url: 'https://registry.npmjs.org'
+ cache: 'npm'
+
+ - name: Install dependencies
+ run: npm install
+
+ - name: Resolve version
+ id: version
+ run: |
+ set -euo pipefail
+ VERSION=$(node -p "require('./cli/package.json').version")
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ # `npm view` exits non-zero for an unpublished name/version; an empty
+ # result is the signal to publish, not an error.
+ PUBLISHED=$(npm view "freellmapi@$VERSION" version 2>/dev/null || true)
+ if [ -n "$PUBLISHED" ]; then
+ echo "freellmapi@$VERSION is already on the registry — nothing to do."
+ echo "should-publish=false" >> "$GITHUB_OUTPUT"
+ else
+ echo "freellmapi@$VERSION is not published yet."
+ echo "should-publish=true" >> "$GITHUB_OUTPUT"
+ fi
+
+ # `npm publish` runs cli's prepublishOnly (build + test) as a safety net.
+ # Building here as well keeps a broken tsc from reaching the publish step.
+ - name: Build and test the CLI
+ if: steps.version.outputs.should-publish == 'true'
+ run: |
+ npm run build -w cli
+ npm run test -w cli
+
+ - name: Smoke-test the packed tarball
+ if: steps.version.outputs.should-publish == 'true'
+ run: |
+ set -euo pipefail
+ # Install what subscribers will actually download — catches a `files`
+ # array that omits a runtime import, which `npm test` cannot see.
+ TARBALL=$(cd cli && npm pack --silent --pack-destination "$RUNNER_TEMP")
+ WORKDIR="$RUNNER_TEMP/smoke"
+ mkdir -p "$WORKDIR" && cd "$WORKDIR"
+ npm init -y >/dev/null
+ npm install "$RUNNER_TEMP/$TARBALL" >/dev/null
+ npx freellmapi --help
+ npx freellmapi list >/dev/null
+
+ # No NODE_AUTH_TOKEN: the OIDC credential comes from id-token: write.
+ # Provenance is attached automatically under trusted publishing.
+ - name: Publish
+ if: steps.version.outputs.should-publish == 'true'
+ run: npm publish --access public -w cli
+
+ - name: Summary
+ if: always()
+ run: |
+ V="${{ steps.version.outputs.version }}"
+ if [ "${{ steps.version.outputs.should-publish }}" = "true" ]; then
+ echo "Published freellmapi@$V" >> "$GITHUB_STEP_SUMMARY"
+ else
+ echo "freellmapi@$V is already on the registry — skipped." >> "$GITHUB_STEP_SUMMARY"
+ fi
diff --git a/README.md b/README.md
index 0eb38c65..f5769825 100644
--- a/README.md
+++ b/README.md
@@ -188,7 +188,7 @@ Anything that can target an OpenAI-compatible base URL works: set it to `http://
The fastest setup is generated from the models available on your live server:
```bash
-npx freellmapi setup-claude --url http://localhost:3001
+npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>
```
Every generator supports `--dry-run`, creates a timestamped backup before changing an existing file, and merges into the user's configuration. Launchers keep credentials out of config files entirely: `npx freellmapi launch` for Claude Code and `npx freellmapi launch-codex` for Codex.
diff --git a/cli/LICENSE b/cli/LICENSE
new file mode 100644
index 00000000..8eb2b075
--- /dev/null
+++ b/cli/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tashfeen Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 00000000..1984ee67
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,66 @@
+# freellmapi
+
+Point your coding agent at a [FreeLLMAPI](https://github.com/tashfeenahmed/freellmapi)
+gateway in one command. The generators read the models your server is actually
+serving and write the config file each tool expects.
+
+```bash
+npx freellmapi setup-claude --url http://localhost:3001 --api-key <your-key>
+```
+
+No install step, no account. The unified API key comes from your FreeLLMAPI
+dashboard (or the tray popover in the desktop app).
+
+## Commands
+
+| Command | Tool |
+| --- | --- |
+| `setup-claude` | Claude Code |
+| `setup-codex` | Codex CLI |
+| `setup-cline` | Cline |
+| `setup-continue` | Continue |
+| `setup-aider` | Aider |
+| `setup-opencode` | OpenCode |
+| `setup-goose` | Goose |
+| `setup-qwen` | Qwen Code |
+| `setup-roo` | Roo Code |
+| `setup-kilo` | Kilo Code |
+| `setup-crush` | Crush |
+| `setup-cursor` | Cursor |
+| `setup-generic` | Any OpenAI-compatible client |
+| `launch` | Run Claude Code with credentials injected into the child process |
+| `launch-codex` | Run Codex the same way |
+| `list` | Print the supported tools and their base URLs |
+
+## Options
+
+| Flag | Meaning |
+| --- | --- |
+| `--url URL` | Gateway base URL (default `http://localhost:3001`) |
+| `--api-key KEY` | Unified API key |
+| `--profile NAME` | Name the generated profile/provider entry |
+| `--model ID` | Pin a specific model instead of the catalog default |
+| `--dry-run` | Print the diff and write nothing |
+
+`FREELLMAPI_URL` and `FREELLMAPI_API_KEY` work in place of `--url` / `--api-key`.
+
+## Safety
+
+Every generator is non-destructive: it merges into your existing configuration
+rather than replacing it, and takes a timestamped backup before touching a file
+that already exists. `--dry-run` shows the exact diff first.
+
+The two `launch` commands never write credentials to disk at all — they inject
+them into the child process environment for that run only.
+
+## Requirements
+
+Node.js >= 20.18. A running FreeLLMAPI gateway
+([install guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.md)).
+
+## Links
+
+- [Clients & coding agents guide](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/clients.md)
+- [Issue tracker](https://github.com/tashfeenahmed/freellmapi/issues)
+
+MIT © Tashfeen Ahmed
diff --git a/cli/package.json b/cli/package.json
index 86b9d8d9..50774bff 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -8,15 +8,32 @@
"url": "git+https://github.com/tashfeenahmed/freellmapi.git",
"directory": "cli"
},
+ "homepage": "https://github.com/tashfeenahmed/freellmapi/tree/main/cli#readme",
+ "bugs": {
+ "url": "https://github.com/tashfeenahmed/freellmapi/issues"
+ },
+ "keywords": [
+ "freellmapi",
+ "llm",
+ "openai-compatible",
+ "claude-code",
+ "codex",
+ "aider",
+ "cline",
+ "coding-agent",
+ "cli"
+ ],
"type": "module",
"bin": {
- "freellmapi": "./dist/index.js"
+ "freellmapi": "dist/index.js"
},
"exports": {
".": "./dist/index.js",
"./tools": "./dist/tools.js"
},
"files": [
+ "README.md",
+ "LICENSE",
"dist/index.js",
"dist/index.d.ts",
"dist/config-files.js",
diff --git a/docs/clients.md b/docs/clients.md
index 5fe885c8..52a32940 100644
--- a/docs/clients.md
+++ b/docs/clients.md
@@ -25,6 +25,7 @@ Any client that can target an OpenAI-compatible base URL can use FreeLLMAPI:
Use the generator instead of hand-editing a client configuration:
```bash
+export FREELLMAPI_API_KEY=<unified-key> # or pass --api-key on each command
npx freellmapi setup-claude --url http://localhost:3001 --dry-run
npx freellmapi setup-claude --url http://localhost:3001
```