@liaisonio/cli 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# Liaison Cloud CLI
+
+Official command-line interface for [liaison.cloud](https://liaison.cloud), designed
+to be **scripted and agent-friendly**.
+
+- JSON output by default — ready for piping into `jq` or parsing by LLM agents
+- `--output table` for humans, `--output yaml` when you prefer it
+- Credentials from env var (`LIAISON_TOKEN`), config file, or explicit `--token` flag
+- Every command has `-h` / `--help` with examples
+- Non-interactive by default: destructive operations require `--yes`
+
+## Install
+
+Pick whichever fits your environment. All paths land at the same versioned binary.
+
+### One-line installer (curl, recommended)
+
+```bash
+curl -fsSL https://github.com/liaisonio/cli/releases/latest/download/install.sh | sh
+```
+
+Auto-detects OS/arch, verifies SHA256, drops the binary in `~/.local/bin` (or
+`/usr/local/bin` with sudo if `~/.local/bin` is not writable). Pin a version with
+`LIAISON_CLI_VERSION=v0.1.0`.
+
+### npx / npm
+
+```bash
+# Run once without installing
+npx @liaisonio/cli edge list
+
+# Or install globally
+npm i -g @liaisonio/cli
+liaison edge list
+```
+
+The npm wrapper is a thin Node.js shim that downloads the matching native binary
+from the GitHub release on `postinstall`, verifies its SHA256, and execs it.
+
+### Go install
+
+```bash
+go install github.com/liaisonio/cli/cmd/liaison@latest
+```
+
+Requires Go 1.22+. Best for Go developers who already have `$GOPATH/bin` in their PATH.
+
+### Build from source
+
+```bash
+git clone https://github.com/liaisonio/cli
+cd cli
+make build           # ./bin/liaison           (current platform)
+make release         # ./dist/liaison-*        (all 5 platforms + SHA256SUMS)
+```
+
+### Verify
+
+```bash
+liaison version
+```
+
+## Authenticate
+
+The CLI accepts a JWT bearer token issued by liaison.cloud. For now the slider-captcha
+login flow used by the web UI is not supported headlessly — you need to obtain the
+token out of band:
+
+1. Log in to [liaison.cloud](https://liaison.cloud) in your browser.
+2. Open DevTools → Application → Local Storage → copy the `authorization` value.
+3. Persist it:
+
+   ```bash
+   liaison login --token eyJhbGciOi...
+   ```
+
+   This writes `~/.liaison/config.yaml` (mode 0600) and verifies the token against
+   `/api/v1/iam/profile_json`.
+
+Alternatively, skip the config file entirely and pass the token per-invocation:
+
+```bash
+LIAISON_TOKEN=eyJhbGciOi... liaison edge list
+# or
+liaison --token eyJhbGciOi... edge list
+```
+
+Precedence (highest wins): `--token` flag → `LIAISON_TOKEN` env → config file → built-in default.
+
+## Usage
+
+```bash
+liaison whoami                                    # who am I logged in as?
+
+# Connectors (edges)
+liaison edge list
+liaison edge list --online 1                      # only online connectors
+liaison edge list --output table
+liaison edge get 100017
+liaison edge create --name lab-server --description "office lab"
+liaison edge update 100017 --status stopped       # disable + kick
+liaison edge update 100017 --status running       # re-enable
+liaison edge delete 100017 --yes
+
+# Backend applications (IP:port exposed by a connector)
+liaison application list
+liaison application create --name my-ssh --protocol ssh --ip 192.168.1.10 --port 22 --edge-id 100017
+liaison application update 123 --port 2222
+liaison application delete 123 --yes
+
+# Entries (public proxies)
+liaison proxy list
+liaison proxy create --name my-ssh-entry --protocol ssh --application-id 123
+liaison proxy update 456 --status stopped
+liaison proxy delete 456 --yes
+
+# Devices
+liaison device list
+liaison device get 789
+```
+
+## Global flags
+
+| Flag          | Env              | Description                                           |
+|---------------|------------------|-------------------------------------------------------|
+| `--server`    | `LIAISON_SERVER` | Liaison base URL (default `https://liaison.cloud`)    |
+| `--token`     | `LIAISON_TOKEN`  | JWT bearer token                                      |
+| `--config`    |                  | Config file path (default `~/.liaison/config.yaml`)   |
+| `--output,-o` |                  | `json` (default), `yaml`, or `table`                  |
+| `--insecure`  |                  | Skip TLS verification (self-signed testing only)      |
+| `--verbose,-v`|                  | Print each HTTP request to stderr                     |
+
+## Output formats
+
+```bash
+liaison edge list                    # pretty JSON (default)
+liaison edge list -o yaml            # YAML
+liaison edge list -o table           # aligned text table
+liaison edge get 100017 | jq .name   # pipe into jq
+```
+
+## Exit codes
+
+- `0` — success
+- `1` — any error (auth, network, API error, invalid args)
+
+Error messages go to stderr; output goes to stdout — safe to redirect.
+
+## Agent guidance
+
+If you are an LLM agent, here's the minimal path:
+
+**Install** (pick the first one that works in your environment):
+
+```bash
+# Option 1: npx — no install, works in any node-equipped sandbox
+npx -y @liaisonio/cli@latest <command>
+
+# Option 2: curl one-liner — works on any unix shell with curl
+curl -fsSL https://github.com/liaisonio/cli/releases/latest/download/install.sh | sh
+
+# Option 3: go install — if Go toolchain is already present
+go install github.com/liaisonio/cli/cmd/liaison@latest
+```
+
+**Authenticate**:
+
+```bash
+# Best: ask the user to put a Personal Access Token in your secrets store as LIAISON_TOKEN.
+# Then every command works without any login flow:
+LIAISON_TOKEN=liaison_pat_... liaison whoami
+```
+
+**Use**:
+
+1. Always parse stdout as JSON (it's the default output format).
+2. Discover commands with `liaison --help` and `liaison <resource> --help`. Every flag
+   has a description and examples.
+3. Never omit `--yes` for `delete` actions — the CLI refuses to proceed without it.
+4. Don't retry on exit code 1 — read the error message on stderr first.
+5. Errors go to stderr; data goes to stdout. Safe to redirect them separately.
+
+## License
+
+Apache 2.0

package/bin/liaison.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+//
+// Entry point listed in package.json "bin". This file is what `npx
+// @liaisonio/cli ...` and the symlinked `liaison` command both call.
+//
+// All it does is locate the platform-specific Go binary that was downloaded
+// during `postinstall` (see scripts/install.js) and exec it, forwarding
+// argv, stdio, and the exit code.
+//
+// We deliberately do NOT use require('child_process').execFile or .exec here
+// because they buffer stdout/stderr — the CLI prints progress lines for
+// `liaison login`, and we want the user to see them in real time.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const PLATFORM_BINARY = {
+  'darwin-arm64': 'liaison',
+  'darwin-x64': 'liaison',
+  'linux-arm64': 'liaison',
+  'linux-x64': 'liaison',
+  'win32-x64': 'liaison.exe',
+};
+
+function fail(msg, code) {
+  process.stderr.write(`liaison-cli: ${msg}\n`);
+  process.exit(code || 1);
+}
+
+const key = `${process.platform}-${process.arch}`;
+const binaryName = PLATFORM_BINARY[key];
+if (!binaryName) {
+  fail(
+    `unsupported platform ${key}. Supported: ${Object.keys(PLATFORM_BINARY).join(', ')}`,
+  );
+}
+
+const binaryPath = path.join(__dirname, '..', 'vendor', binaryName);
+if (!fs.existsSync(binaryPath)) {
+  fail(
+    `binary not found at ${binaryPath}.\n` +
+      'This usually means the postinstall download was skipped or failed.\n' +
+      'Try: npm rebuild @liaisonio/cli  (or `npm install` again with --foreground-scripts)',
+  );
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+if (result.error) {
+  fail(`failed to run binary: ${result.error.message}`);
+}
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@liaisonio/cli",
+  "version": "0.1.0",
+  "description": "Liaison Cloud CLI — manage connectors, entries, and applications from the command line",
+  "keywords": ["liaison", "liaison-cloud", "cli", "edge", "tunnel", "agent"],
+  "homepage": "https://liaison.cloud",
+  "license": "Apache-2.0",
+  "author": "Liaison Cloud",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liaisonio/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/liaisonio/cli/issues"
+  },
+  "bin": {
+    "liaison": "bin/liaison.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+//
+// Postinstall hook for @liaisonio/cli.
+//
+// Downloads the platform-specific Go binary from the matching GitHub release
+// and verifies its SHA256 against the published SHA256SUMS file. The binary is
+// dropped at vendor/<liaison|liaison.exe> next to this script's parent.
+//
+// Skipped automatically when:
+//   - LIAISON_CLI_SKIP_DOWNLOAD=1 (dev / CI scenarios that don't need the bin)
+//   - The user is on an unsupported platform (we exit 0 + warn, NOT fail,
+//     so npm install doesn't break for transitive deps)
+//
+// Network failures DO fail the install — silently shipping a broken package
+// is worse than a clear error the user can retry.
+
+'use strict';
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const pkg = require('../package.json');
+const VERSION = `v${pkg.version}`;
+const REPO = 'liaisonio/cli';
+const RELEASE_BASE = `https://github.com/${REPO}/releases/download/${VERSION}`;
+
+// process.platform-process.arch → release asset GOOS-GOARCH suffix.
+const PLATFORMS = {
+  'darwin-arm64': { os: 'darwin', arch: 'arm64', ext: '' },
+  'darwin-x64': { os: 'darwin', arch: 'amd64', ext: '' },
+  'linux-arm64': { os: 'linux', arch: 'arm64', ext: '' },
+  'linux-x64': { os: 'linux', arch: 'amd64', ext: '' },
+  'win32-x64': { os: 'windows', arch: 'amd64', ext: '.exe' },
+};
+
+function log(msg) {
+  process.stdout.write(`liaison-cli: ${msg}\n`);
+}
+
+function warn(msg) {
+  process.stderr.write(`liaison-cli: ${msg}\n`);
+}
+
+function die(msg) {
+  warn(msg);
+  process.exit(1);
+}
+
+if (process.env.LIAISON_CLI_SKIP_DOWNLOAD === '1') {
+  log('LIAISON_CLI_SKIP_DOWNLOAD=1, skipping binary download');
+  process.exit(0);
+}
+
+const key = `${process.platform}-${process.arch}`;
+const platform = PLATFORMS[key];
+if (!platform) {
+  warn(
+    `unsupported platform ${key}; package installed without a binary. ` +
+      `Use --ignore-scripts or set LIAISON_CLI_SKIP_DOWNLOAD=1 to silence.`,
+  );
+  // Exit 0 so transitive dependents don't break.
+  process.exit(0);
+}
+
+const filename = `liaison-${VERSION}-${platform.os}-${platform.arch}${platform.ext}`;
+const url = `${RELEASE_BASE}/${filename}`;
+const sumsUrl = `${RELEASE_BASE}/SHA256SUMS`;
+
+const vendorDir = path.join(__dirname, '..', 'vendor');
+const destPath = path.join(vendorDir, `liaison${platform.ext}`);
+
+fs.mkdirSync(vendorDir, { recursive: true });
+
+// Followed-redirect HTTP GET that streams to a file.
+function downloadToFile(targetUrl, outPath) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(outPath);
+    function get(u, depth) {
+      if (depth > 5) {
+        reject(new Error(`too many redirects fetching ${targetUrl}`));
+        return;
+      }
+      https
+        .get(u, { headers: { 'User-Agent': 'liaison-cli-installer' } }, (res) => {
+          if (
+            res.statusCode &&
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location
+          ) {
+            res.resume();
+            get(res.headers.location, depth + 1);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+            res.resume();
+            return;
+          }
+          res.pipe(file);
+          file.on('finish', () => file.close(() => resolve()));
+          file.on('error', reject);
+        })
+        .on('error', reject);
+    }
+    get(targetUrl, 0);
+  });
+}
+
+function downloadToString(targetUrl) {
+  return new Promise((resolve, reject) => {
+    function get(u, depth) {
+      if (depth > 5) {
+        reject(new Error(`too many redirects fetching ${targetUrl}`));
+        return;
+      }
+      https
+        .get(u, { headers: { 'User-Agent': 'liaison-cli-installer' } }, (res) => {
+          if (
+            res.statusCode &&
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location
+          ) {
+            res.resume();
+            get(res.headers.location, depth + 1);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+            res.resume();
+            return;
+          }
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (chunk) => (body += chunk));
+          res.on('end', () => resolve(body));
+        })
+        .on('error', reject);
+    }
+    get(targetUrl, 0);
+  });
+}
+
+function sha256(filepath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filepath));
+  return hash.digest('hex');
+}
+
+async function main() {
+  log(`fetching ${url}`);
+  await downloadToFile(url, destPath);
+  fs.chmodSync(destPath, 0o755);
+
+  log('verifying SHA256');
+  const sums = await downloadToString(sumsUrl);
+  const line = sums
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.endsWith(filename));
+  if (!line) {
+    fs.unlinkSync(destPath);
+    die(`no SHA256 entry for ${filename} in SHA256SUMS — release may be corrupt`);
+  }
+  const expected = line.split(/\s+/)[0];
+  const actual = sha256(destPath);
+  if (expected !== actual) {
+    fs.unlinkSync(destPath);
+    die(`SHA256 mismatch for ${filename}: expected ${expected}, got ${actual}`);
+  }
+  log(`installed ${filename} (sha256 ok)`);
+}
+
+main().catch((err) => {
+  die(`download failed: ${err.message}`);
+});