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.ymlnew file mode 100644index 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"+ fidiff --git a/README.md b/README.mdindex 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/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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 Ahmeddiff --git a/cli/package.json b/cli/package.jsonindex 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.mdindex 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 commandnpx freellmapi setup-claude --url http://localhost:3001 --dry-runnpx freellmapi setup-claude --url http://localhost:3001```