@pygg/cli 0.1.0-dev.0 → 0.1.0-dev.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -8
- package/bin/pygg.js +140 -23
- package/package.json +18 -3
package/README.md
CHANGED
|
@@ -1,18 +1,98 @@
|
|
|
1
1
|
# @pygg/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Source, issues and releases: [github.com/nambean/Pygg](https://github.com/nambean/Pygg)**. Pygg is open source (MIT), and contributions are welcome.
|
|
4
|
+
|
|
5
|
+
`pygg`: route your AI coding tools (Claude Code, Codex, OpenCode) through Pygg, a local gateway that picks a model for each request from the providers you connected, and records what each request cost.
|
|
6
|
+
|
|
7
|
+
**npm installs this command only**, on Windows x64, macOS (Apple silicon and Intel) and Linux x64 (glibc): npm fetches the native program for your computer only. On Windows the [Pygg desktop app](https://github.com/nambean/Pygg) runs the gateway and is where you connect providers; on macOS and Linux, where there is no app yet, `pygg gateway add-connection` and `pygg gateway serve` do it from the terminal. Your coding tools are installed as usual. **`@dev` is a developer preview**: the native program is not code-signed, so Windows SmartScreen, macOS Gatekeeper or an antivirus may warn about it.
|
|
8
|
+
|
|
9
|
+
## Start here
|
|
10
|
+
|
|
11
|
+
1. Install and open the Pygg desktop app, and connect a provider (Providers > Connect Provider).
|
|
12
|
+
2. Install the command, and see where you are:
|
|
4
13
|
|
|
5
14
|
```
|
|
6
15
|
npm install -g @pygg/cli@dev
|
|
7
|
-
pygg
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
pygg
|
|
11
|
-
|
|
16
|
+
pygg
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`pygg` alone shows whether the gateway is running, your providers, which tools are set up, and the next thing to type.
|
|
20
|
+
|
|
21
|
+
3. Set up a tool and start it through Pygg:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
pygg setup claude # Claude Code: a key of its own, kept in the system's credential store; no file changes
|
|
25
|
+
pygg run claude # Claude Code through Pygg, with the model auto; plain `claude` keeps your Claude sign-in
|
|
26
|
+
|
|
27
|
+
pygg setup codex # Codex: Pygg's provider and profile in config.toml, after a backup
|
|
28
|
+
pygg run codex
|
|
29
|
+
|
|
30
|
+
pygg setup opencode # OpenCode: Pygg's provider in opencode.json, after a backup
|
|
31
|
+
pygg run opencode # then choose a Pygg model with /models (pygg/auto lets Pygg choose)
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`--dry-run` previews a setup and writes nothing; `--remove` undoes it and revokes the key Pygg made. Setup sends no prompt; requests your tool makes later may cost money, as the providers you connected charge them.
|
|
35
|
+
|
|
36
|
+
Each `pygg run` launch gets its own routing session: the gateway keeps it on the model that answered it while that model stays eligible, so the provider's prompt cache is kept. Pygg's own options go before the tool's name (`pygg run --model auto/cheap claude`); everything after it is the tool's (`pygg run claude --help` is Claude Code's help).
|
|
37
|
+
|
|
38
|
+
## See what Pygg has and does
|
|
39
|
+
|
|
40
|
+
These only read Pygg's store; they send nothing to any provider. Each takes `--json` (a document with `schemaVersion: 1`) for scripts.
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
pygg status # is the gateway answering, and on which store
|
|
44
|
+
pygg doctor # status, plus your tools and the providers that need attention
|
|
45
|
+
pygg providers # saved connections: on, last check, health over 24 hours, models
|
|
46
|
+
pygg models --search flash # the models to ask for (CONNECTION/MODEL), with billing and price
|
|
47
|
+
pygg logs --failed # recent request attempts, newest first (--limit N, --client NAME)
|
|
48
|
+
pygg usage --days 7 # requests, known and unknown cost, token mix, by client and model
|
|
12
49
|
```
|
|
13
50
|
|
|
14
|
-
|
|
51
|
+
Exit codes: 0 done, 1 failed, 2 wrong usage, 3 a check found a problem (`status`, `doctor`); `run` returns the tool's own.
|
|
52
|
+
|
|
53
|
+
`pygg --help` lists every command; `pygg <command> --help` says more.
|
|
54
|
+
|
|
55
|
+
## Try it without installing globally
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
npx --yes --package=@pygg/cli@dev pygg
|
|
59
|
+
npx --yes --package=@pygg/cli@dev pygg setup claude
|
|
60
|
+
npx --yes --package=@pygg/cli@dev pygg run claude
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
npx downloads the package into npm's cache and runs it. Its `--yes` only approves that download: it does not approve any change Pygg makes, and `setup` still changes your tool's configuration as the installed command does.
|
|
64
|
+
|
|
65
|
+
## If `pygg` is not found
|
|
66
|
+
|
|
67
|
+
Open a new terminal first. Then see where npm put it, and add that folder to your user PATH if it is missing:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
where.exe pygg
|
|
71
|
+
npm prefix -g
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
If PowerShell refuses to run scripts, call `pygg.cmd` instead of `pygg`. `pygg --launcher-info` prints which native program the command runs and where it looked.
|
|
75
|
+
|
|
76
|
+
## How it works
|
|
77
|
+
|
|
78
|
+
`pygg` is a small Node launcher. It runs the native `pygg-cli` program from the package for your computer (`@pygg/win32-x64`, `@pygg/darwin-arm64`, `@pygg/darwin-x64` or `@pygg/linux-x64`), which npm installs with it as an optional dependency, with the same arguments and standard streams, and exits with its code. On Windows, without that package, it uses an installed Pygg app's `pygg-cli.exe` (`%LOCALAPPDATA%\Pygg`). `PYGG_CLI`, set to the full path of a `pygg-cli` program, takes precedence. Where no program is published (Alpine and other musl Linux, Windows on Arm with an Arm Node, other systems), or npm skipped it (`--omit=optional`), `pygg` says so and what to do.
|
|
79
|
+
|
|
80
|
+
On macOS and Linux the API keys Pygg makes are kept in the Keychain or the desktop keyring (Secret Service); the store is in `~/Library/Application Support/app.smarttaskrouter.desktop` or `~/.local/share/app.smarttaskrouter.desktop` (`PYGG_DATA_DIR` changes it).
|
|
81
|
+
|
|
82
|
+
Two things the command does not do: it never starts a gateway by itself (the app serves it, or `pygg gateway serve` does, on purpose), and it never takes an API key on the command line.
|
|
83
|
+
|
|
84
|
+
## Experimental: tasks from your IDE
|
|
85
|
+
|
|
86
|
+
`pygg mcp setup claude-code`, `pygg mcp setup codex` and `pygg mcp setup opencode` register Pygg's MCP server (`pygg mcp`) in the tool, so it can hand coding tasks to Pygg. That is the experimental task integration, on hold; it is not how a tool's requests go through the gateway (see Start here).
|
|
87
|
+
|
|
88
|
+
## Contributing
|
|
89
|
+
|
|
90
|
+
Pygg is built in the open at [github.com/nambean/Pygg](https://github.com/nambean/Pygg), and help is welcome:
|
|
91
|
+
|
|
92
|
+
- **Report a bug or ask for something**: [open an issue](https://github.com/nambean/Pygg/issues). Say what you ran, what you expected and what `pygg doctor` prints; never paste an API key.
|
|
93
|
+
- **Send a change**: read [CONTRIBUTING](https://github.com/nambean/Pygg/blob/main/CONTRIBUTING.md), then open a pull request. Provider presets, platform fixes (macOS and Linux especially), documentation and tests are good places to start.
|
|
94
|
+
- **Star the repository** if Pygg is useful to you: it helps others find it.
|
|
15
95
|
|
|
16
|
-
|
|
96
|
+
Security problems go privately, as [SECURITY](https://github.com/nambean/Pygg/blob/main/docs/SECURITY.md) describes, not in a public issue.
|
|
17
97
|
|
|
18
98
|
MIT licence.
|
package/bin/pygg.js
CHANGED
|
@@ -1,42 +1,159 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// `pygg` from npm (@pygg/cli): finds the native `pygg-cli` program and runs it with the same
|
|
3
|
-
// and output (so `pygg mcp` works as an MCP server for coding agents) and exits with its
|
|
4
|
-
//
|
|
2
|
+
// `pygg` from npm (@pygg/cli): finds the native `pygg-cli` program for this computer and runs it with the same
|
|
3
|
+
// arguments, standard input and output (so `pygg mcp` works as an MCP server for coding agents), and exits with its
|
|
4
|
+
// code. One package for every platform (ADR-037): npm installs only the platform package that matches this computer,
|
|
5
|
+
// from the optional dependencies (@pygg/win32-x64, @pygg/darwin-arm64, @pygg/darwin-x64, @pygg/linux-x64), as esbuild
|
|
6
|
+
// and Biome do. The program comes, in this order, from PYGG_CLI (a full path, when set), from that platform package,
|
|
7
|
+
// or from an installed Pygg app (Windows). `pygg --launcher-info` says which, without starting anything.
|
|
5
8
|
'use strict';
|
|
6
9
|
|
|
7
|
-
const {
|
|
10
|
+
const { spawn } = require('node:child_process');
|
|
8
11
|
const fs = require('node:fs');
|
|
9
12
|
const path = require('node:path');
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
/** The platforms a native program is published for, by npm's `<os>-<cpu>` name. Linux builds are for glibc. */
|
|
15
|
+
const PLATFORMS = ['win32-x64', 'darwin-arm64', 'darwin-x64', 'linux-x64'];
|
|
16
|
+
const INSTALL = 'npm install -g @pygg/cli@dev';
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
|
|
18
|
+
/** Whether this Node runs on glibc (most Linux distributions) rather than musl (Alpine). */
|
|
19
|
+
function isGlibc(report = safeReport()) {
|
|
20
|
+
return Boolean(report && report.header && report.header.glibcVersionRuntime);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function safeReport() {
|
|
15
24
|
try {
|
|
16
|
-
return
|
|
25
|
+
return process.report && typeof process.report.getReport === 'function' ? process.report.getReport() : null;
|
|
17
26
|
} catch {
|
|
18
27
|
return null;
|
|
19
28
|
}
|
|
20
29
|
}
|
|
21
30
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
31
|
+
/**
|
|
32
|
+
* What this computer needs: its npm platform name, the package that holds its program, the program's file name, and,
|
|
33
|
+
* when none is published for it, why and what to do instead.
|
|
34
|
+
*/
|
|
35
|
+
function target(platform = process.platform, arch = process.arch, glibc = platform === 'linux' ? isGlibc() : true) {
|
|
36
|
+
const name = `${platform}-${arch}`;
|
|
37
|
+
const exe = platform === 'win32' ? 'pygg-cli.exe' : 'pygg-cli';
|
|
38
|
+
const pkg = `@pygg/${name}`;
|
|
39
|
+
let unsupported = null;
|
|
40
|
+
if (!PLATFORMS.includes(name)) {
|
|
41
|
+
unsupported = platform === 'win32' && arch === 'arm64'
|
|
42
|
+
? 'Windows on Arm: install the x64 build of Node.js (Windows runs it emulated) and reinstall, so npm picks @pygg/win32-x64.'
|
|
43
|
+
: `No native program is published for ${name} yet; there are builds for ${PLATFORMS.join(', ')}.`;
|
|
44
|
+
} else if (platform === 'linux' && !glibc) {
|
|
45
|
+
unsupported = 'This Linux uses musl (Alpine, for example); the published Linux program needs glibc. Use a glibc-based image such as Debian or Ubuntu.';
|
|
46
|
+
}
|
|
47
|
+
return { name, exe, pkg, unsupported };
|
|
25
48
|
}
|
|
26
49
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
50
|
+
/** Where the program may be, in order, each with where it came from. */
|
|
51
|
+
function candidates(t, env = process.env, resolve = require.resolve) {
|
|
52
|
+
if (env.PYGG_CLI) {
|
|
53
|
+
// Only a full path: a relative one would run whatever program of that name is in the current folder.
|
|
54
|
+
return [{ source: 'PYGG_CLI', program: path.isAbsolute(env.PYGG_CLI) ? env.PYGG_CLI : null }];
|
|
55
|
+
}
|
|
56
|
+
let fromPackage = null;
|
|
57
|
+
try {
|
|
58
|
+
fromPackage = path.join(path.dirname(resolve(`${t.pkg}/package.json`)), 'bin', t.exe);
|
|
59
|
+
} catch {
|
|
60
|
+
// Not installed: npm skipped it (another platform, or optional dependencies omitted).
|
|
61
|
+
}
|
|
62
|
+
const list = [{ source: `the package ${t.pkg}`, program: fromPackage }];
|
|
63
|
+
if (t.name.startsWith('win32-') && env.LOCALAPPDATA) {
|
|
64
|
+
list.push({ source: 'the installed Pygg app', program: path.join(env.LOCALAPPDATA, 'Pygg', t.exe) });
|
|
65
|
+
}
|
|
66
|
+
return list;
|
|
32
67
|
}
|
|
33
68
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
69
|
+
/** The lines that say why nothing can run, and what to do. */
|
|
70
|
+
function notFound(t, list, env = process.env) {
|
|
71
|
+
if (env.PYGG_CLI) {
|
|
72
|
+
return path.isAbsolute(env.PYGG_CLI)
|
|
73
|
+
? [`pygg: PYGG_CLI points to a program that is not there: ${env.PYGG_CLI}`]
|
|
74
|
+
: [`pygg: PYGG_CLI must be the full path of a pygg-cli program, not "${env.PYGG_CLI}".`];
|
|
75
|
+
}
|
|
76
|
+
if (t.unsupported) {
|
|
77
|
+
return [`pygg: ${t.unsupported}`, 'Or set PYGG_CLI to the full path of a pygg-cli program you built yourself (cargo build --release --no-default-features --bin pygg-cli).'];
|
|
78
|
+
}
|
|
79
|
+
const looked = list.filter(c => c.program).map(c => ` ${c.program} (${c.source})`);
|
|
80
|
+
return [
|
|
81
|
+
`pygg: the native program for ${t.name} (${t.pkg}) is not installed.${looked.length ? ' Looked in:' : ''}`,
|
|
82
|
+
...looked,
|
|
83
|
+
`npm installs it as an optional dependency; it is skipped with --omit=optional or --no-optional. Reinstall with:`,
|
|
84
|
+
` ${INSTALL}`,
|
|
85
|
+
'or set PYGG_CLI to the full path of a pygg-cli program.',
|
|
86
|
+
];
|
|
38
87
|
}
|
|
39
|
-
|
|
40
|
-
|
|
88
|
+
|
|
89
|
+
/** On macOS and Linux, a program unpacked without its execute bit gets it back when the user may set it. */
|
|
90
|
+
function ensureExecutable(program) {
|
|
91
|
+
if (process.platform === 'win32') return null;
|
|
92
|
+
try {
|
|
93
|
+
fs.accessSync(program, fs.constants.X_OK);
|
|
94
|
+
return null;
|
|
95
|
+
} catch {
|
|
96
|
+
try {
|
|
97
|
+
fs.chmodSync(program, 0o755);
|
|
98
|
+
return null;
|
|
99
|
+
} catch (e) {
|
|
100
|
+
return `pygg: ${program} is not executable and could not be made so (${e.code || e.message}). Run: chmod +x "${program}"`;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
41
103
|
}
|
|
42
|
-
|
|
104
|
+
|
|
105
|
+
function fail(lines, code = 1) {
|
|
106
|
+
// Errors go to stderr only: stdout stays the native program's, which matters for `pygg mcp`.
|
|
107
|
+
console.error(lines.join('\n'));
|
|
108
|
+
process.exit(code);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function main() {
|
|
112
|
+
const t = target();
|
|
113
|
+
const list = candidates(t);
|
|
114
|
+
const found = list.find(c => c.program && fs.existsSync(c.program));
|
|
115
|
+
|
|
116
|
+
if (process.argv[2] === '--launcher-info') {
|
|
117
|
+
const version = require('../package.json').version;
|
|
118
|
+
console.log(`@pygg/cli ${version} on ${t.name}${t.unsupported ? ` (${t.unsupported})` : ''}`);
|
|
119
|
+
for (const c of list) {
|
|
120
|
+
const state = !c.program ? 'not installed' : fs.existsSync(c.program) ? 'found' : 'not there';
|
|
121
|
+
console.log(` ${c === found ? '*' : ' '} ${c.source}: ${c.program || '-'} (${state})`);
|
|
122
|
+
}
|
|
123
|
+
console.log(found ? `Runs ${found.program}` : 'No pygg-cli program found.');
|
|
124
|
+
process.exit(0);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
if (!found) {
|
|
128
|
+
fail(notFound(t, list));
|
|
129
|
+
}
|
|
130
|
+
const notExecutable = ensureExecutable(found.program);
|
|
131
|
+
if (notExecutable) {
|
|
132
|
+
fail([notExecutable]);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const child = spawn(found.program, process.argv.slice(2), { stdio: 'inherit', windowsHide: true });
|
|
136
|
+
// Ctrl+C reaches the program from the terminal itself (`pygg gateway serve` finishes the requests in flight first),
|
|
137
|
+
// so this launcher only waits for it; a signal sent to the launcher alone is passed on.
|
|
138
|
+
process.on('SIGINT', () => {});
|
|
139
|
+
for (const signal of ['SIGTERM', 'SIGHUP']) {
|
|
140
|
+
process.on(signal, () => {
|
|
141
|
+
try { child.kill(signal); } catch { /* it has ended */ }
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
child.on('error', e => fail([`pygg: could not start ${found.program}: ${e.message}`]));
|
|
145
|
+
child.on('exit', (code, signal) => {
|
|
146
|
+
if (signal) {
|
|
147
|
+
process.removeAllListeners(signal);
|
|
148
|
+
process.kill(process.pid, signal);
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
process.exit(code ?? 1);
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
if (require.main === module) {
|
|
156
|
+
main();
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
module.exports = { PLATFORMS, target, candidates, notFound, isGlibc };
|
package/package.json
CHANGED
|
@@ -1,8 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pygg/cli",
|
|
3
|
-
"version": "0.1.0-dev.
|
|
4
|
-
"description": "Pygg
|
|
3
|
+
"version": "0.1.0-dev.2",
|
|
4
|
+
"description": "Route Claude Code, Codex and OpenCode through Pygg, a local AI gateway: set them up, start them through it, and see providers, models, requests and cost. Windows, macOS and Linux. Developer preview, unsigned.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/nambean/Pygg.git",
|
|
9
|
+
"directory": "packages/npm/pygg"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/nambean/Pygg#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/nambean/Pygg/issues"
|
|
14
|
+
},
|
|
6
15
|
"bin": {
|
|
7
16
|
"pygg": "bin/pygg.js"
|
|
8
17
|
},
|
|
@@ -13,8 +22,14 @@
|
|
|
13
22
|
"engines": {
|
|
14
23
|
"node": ">=18"
|
|
15
24
|
},
|
|
25
|
+
"scripts": {
|
|
26
|
+
"test": "node --test test/launcher.test.js"
|
|
27
|
+
},
|
|
16
28
|
"optionalDependencies": {
|
|
17
|
-
"@pygg/
|
|
29
|
+
"@pygg/darwin-arm64": "0.1.0-dev.2",
|
|
30
|
+
"@pygg/darwin-x64": "0.1.0-dev.2",
|
|
31
|
+
"@pygg/linux-x64": "0.1.0-dev.2",
|
|
32
|
+
"@pygg/win32-x64": "0.1.0-dev.2"
|
|
18
33
|
},
|
|
19
34
|
"keywords": [
|
|
20
35
|
"llm",
|