@ratelkey/cli 1.0.1

package/README.md

@@ -0,0 +1,110 @@
+# RatelKey CLI
+
+`ratel` enrols machines into a [RatelKey](https://ratelkey.com) Burrow and reads secrets from it.
+
+A Burrow is a secrets manager you host. This CLI is how a machine joins one and how scripts on that machine read what they are allowed to read.
+
+## Install
+
+```sh
+npm install -g @ratelkey/cli
+```
+
+The published binary is a static Go executable. npm installs the one matching your platform and skips the rest. Linux (x64, arm64, arm), macOS (x64, Apple silicon) and Windows (x64, arm64) are supported.
+
+To run it once without installing:
+
+```sh
+npx @ratelkey/cli <command>
+```
+
+## Enrol a machine
+
+On your Burrow's **Machines** page, click the **(+)** in the table header, name the machine, and choose **Create token**. Run the command it gives you on the machine you are enrolling:
+
+```sh
+npx @ratelkey/cli machine bootstrap <code>
+```
+
+Where the Burrow is reachable from more than one address, the dialog shows a command for **On your network** and one for **Outside your network**. Use the one that matches where the machine sits.
+
+The keypair is generated on that machine. Only the public half is sent to the Burrow; the private key stays on disk and is what every later request is signed with.
+
+The token is one-time and enrols a single machine.
+
+```
+Registered web-01 to my-burrow.
+Machine  4f9c2a10-7b3e-4d51-9a6c-2e8f10b4d773
+Identity /home/you/.burrow/burrows/burrow-a1b2c3d4e5f60718
+```
+
+## Read a secret
+
+The value prints alone on stdout, so it drops straight into a shell variable:
+
+```sh
+export DATABASE_URL=$(ratel secret get myapp/prod/DATABASE_URL)
+```
+
+Set a default environment and bare names resolve against it:
+
+```sh
+ratel environment set myapp/prod
+ratel secret get DATABASE_URL
+```
+
+`RATEL_ENV` overrides the saved default for one invocation:
+
+```sh
+RATEL_ENV=myapp/staging ratel secret get DATABASE_URL
+```
+
+A structured secret prints as JSON, so it pipes into `jq`:
+
+```sh
+ratel secret get myapp/prod/STRIPE | jq -r .publishable_key
+```
+
+Passing a field name selects one field directly:
+
+```sh
+ratel secret get myapp/prod/STRIPE publishable_key
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `ratel machine bootstrap <code>` | Enrol this machine into a Burrow |
+| `ratel secret get <project/env/NAME \| NAME> [field]` | Read a secret's current value |
+| `ratel secret list` | List every secret this machine can read, by slug |
+| `ratel project list` | List the projects this machine can read, and its access in each |
+| `ratel environment set <project/env>` | Set the default environment for bare-name reads |
+| `ratel environment show` | Show the default environment |
+| `ratel whoami` | Show the machine identity and Burrow this CLI acts as |
+| `ratel burrow list` | List the Burrow identities bootstrapped on this machine |
+| `ratel version` | Print the version |
+
+`ratel secret list` prints one slug per line, so it filters:
+
+```sh
+ratel secret list | grep prod
+```
+
+## Several Burrows on one machine
+
+Bootstrapped identities live under `~/.burrow/burrows/<slug>/`. With one on file it is used automatically. With several, name the one you mean. `--burrow` belongs to the subcommand, so it goes after it and before the positional arguments:
+
+```sh
+ratel secret get --burrow my-burrow myapp/prod/DATABASE_URL
+ratel whoami --burrow my-burrow
+```
+
+`RATEL_BURROW` sets it for the session. The selector accepts a name, a machine id, or the Burrow's URL.
+
+## Links
+
+- [ratelkey.com](https://ratelkey.com)
+- [github.com/RatelKeyOrg/ratel-cli](https://github.com/RatelKeyOrg/ratel-cli)
+
+MIT licensed.

package/bin/ratel

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+// Picks the binary for this platform and hands the process over to it.
+//
+// The real CLI is a Go binary; npm is only how it gets onto the machine. Each platform binary is its own
+// package declaring `os` and `cpu`, so npm installs exactly one and the rest are skipped as unmet optional
+// dependencies — which is why they are optionalDependencies rather than dependencies.
+
+const { spawnSync } = require('child_process');
+const os = require('os');
+
+const platformKey = `${os.platform()}-${os.arch()}`;
+
+const packages = {
+  'linux-x64': '@ratelkey/cli-linux-x64/ratel',
+  'linux-arm64': '@ratelkey/cli-linux-arm64/ratel',
+  'linux-arm': '@ratelkey/cli-linux-arm/ratel',
+  'darwin-x64': '@ratelkey/cli-darwin-x64/ratel',
+  'darwin-arm64': '@ratelkey/cli-darwin-arm64/ratel',
+  'win32-x64': '@ratelkey/cli-win32-x64/ratel.exe',
+  'win32-arm64': '@ratelkey/cli-win32-arm64/ratel.exe',
+};
+
+const binary = packages[platformKey];
+if (!binary) {
+  console.error(`ratel: unsupported platform ${platformKey}`);
+  console.error(`Supported: ${Object.keys(packages).join(', ')}`);
+  process.exit(1);
+}
+
+let resolved;
+try {
+  resolved = require.resolve(binary);
+} catch {
+  // Name the package that is missing. It is an optionalDependency, so npm skips it in silence when it
+  // cannot be installed, and the first sign is this failure — at which point "could not find the binary"
+  // sends people looking in the wrong place.
+  const platformPackage = binary.slice(0, binary.lastIndexOf('/'));
+  console.error(`ratel: ${platformPackage} is not installed, so there is no binary for ${platformKey}.`);
+  console.error('It installs automatically with this package. If it did not, reinstall:');
+  console.error('  npm install -g @ratelkey/cli');
+  process.exit(1);
+}
+
+// spawnSync, not execFileSync: execFileSync throws on a non-zero exit, which turns every ordinary CLI
+// failure into a Node stack trace on top of the CLI's own message. This forwards the exit code and stays
+// out of the way. A signal death (Ctrl-C) reports as 130 rather than 0, so a cancelled run doesn't look
+// like a successful one to a script.
+const result = spawnSync(resolved, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) {
+  console.error(`ratel: could not run ${resolved}: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 130);

package/package.json

@@ -0,0 +1 @@
+{"name":"@ratelkey/cli","version":"1.0.1","description":"RatelKey CLI — enrol machines into a Burrow and read its secrets","keywords":["secrets","vault","encryption","cli","ratelkey","burrow","self-hosted"],"homepage":"https://ratelkey.com","repository":{"type":"git","url":"git+https://github.com/RatelKeyOrg/ratel-cli.git"},"bugs":{"url":"https://github.com/RatelKeyOrg/ratel-cli/issues"},"license":"MIT","bin":{"ratel":"bin/ratel"},"files":["bin"],"optionalDependencies":{"@ratelkey/cli-linux-x64":"1.0.1","@ratelkey/cli-linux-arm64":"1.0.1","@ratelkey/cli-linux-arm":"1.0.1","@ratelkey/cli-darwin-x64":"1.0.1","@ratelkey/cli-darwin-arm64":"1.0.1","@ratelkey/cli-win32-x64":"1.0.1","@ratelkey/cli-win32-arm64":"1.0.1"}}