influx-local-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 influx-local-cli contributors
+
+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.

package/README.md

@@ -0,0 +1,265 @@
+# influx-local-cli
+
+Create, start and manage local **InfluxDB** instances without Docker, Podman or
+a system-wide InfluxDB install. Works in both a **CLI** and a **web dashboard**.
+
+`influx-local-cli` follows the same UX as [mongo-local-cli](https://www.npmjs.com/package/mongo-local-cli)
+and [pg-local-cli](https://www.npmjs.com/package/pg-local-cli): multiple named
+instances, first-run setup wizard, one binary for everything.
+
+- **Pick the InfluxDB version per instance** — `1.8.10`, `2.7.11`, `3.11.4`, …
+  each instance pins its own build and they run side by side.
+- **No Docker/Podman** — the pinned build is installed through your existing
+  [mise](https://mise.jdx.dev) toolchain, which fetches the official tarball
+  from `dl.influxdata.com`.
+- **Multiple instances** — `my_app`, `dev_db`, `default`, … each with its own
+  port, data dir, version and credentials.
+- **Daemon** — `start` forks the server; it keeps running after you close the
+  terminal.
+- **Managed credentials** — per line, in `creds.env` (mode 0600), rotatable:
+  - 1.x: an `admin` user (`ALL PRIVILEGES`) and an `app` user (`ALL` on the
+    database),
+  - 2.x: an operator user + all-access token, plus a bucket-scoped app token,
+  - 3.x: a single admin token (3 Core has no per-database scoping).
+- **Web dashboard** — `influx-local web` opens a local UI for all instances:
+  status, start/stop/setup, secret rotation, connection DSNs, version picker,
+  live operation log.
+- **Escape hatches** — `query` runs InfluxQL/Flux/SQL against the instance and
+  `shell` opens the 1.x REPL.
+
+## Requirements
+
+- Node.js ≥ 18
+- [mise](https://mise.jdx.dev) on `PATH` (used to install/run InfluxDB)
+- macOS / Linux (x64 or arm64). Windows is not supported: InfluxData publishes
+  no Windows artifacts for these lines through mise's http backend.
+
+## Install
+
+```bash
+npm install -g influx-local-cli
+```
+
+The binary is `influx-local`.
+
+## Quick start
+
+```bash
+influx-local create my_app          # wizard: version, port, database, users → creds
+influx-local setup my_app           # installs that version, provisions it, starts the server
+influx-local status my_app          # health, running version, measurements, DSNs
+influx-local list                   # all instances and their state (alias: ls)
+```
+
+That's it: you have a local InfluxDB with managed credentials. Data lives in
+`~/.influx-local/instances/<name>/`.
+
+## Choosing the InfluxDB version
+
+The version is a first-class property of an instance: it decides the binaries,
+daemon flags, auth model, storage layout and credentials that the tool manages.
+It can be set when the instance is created and inspected/changed afterwards.
+
+```bash
+influx-local versions                     # catalog, grouped by line (1.x / 2.x / 3.x)
+influx-local versions --json              # machine readable
+influx-local create metrics -v 2.7.11     # pin 2.x explicitly
+influx-local create dev -v 1.x            # line alias → newest 1.x (1.8.10)
+influx-local config show metrics          # what is pinned now
+influx-local config set metrics version 2.9.1
+influx-local install metrics              # (re)install the pinned build through mise
+```
+
+On an interactive terminal `create` also offers an arrow-key picker containing
+every catalog version plus an “enter another published version…” entry, so any
+version InfluxData publishes can be pinned (it is validated against
+`dl.influxdata.com` when installed).
+
+Catalog (verified to exist on `dl.influxdata.com`):
+
+| Line | Auth | Versions | Default |
+| --- | --- | --- | --- |
+| InfluxDB 1.x (InfluxQL) | HTTP basic (users) | 1.7.11, 1.8.0, 1.8.4, 1.8.6, 1.8.9, 1.8.10 | 1.8.10 |
+| InfluxDB 2.x (Flux) | API token | 2.7.3, 2.7.5, 2.7.7, 2.7.9, 2.7.10, 2.7.11, 2.8.0, 2.9.0, 2.9.1 | 2.7.11 |
+| InfluxDB 3 Core (SQL) | API token | 3.0.0, 3.0.3, 3.3.0, 3.4.0, 3.9.0, 3.10.0, 3.10.6, 3.11.2, 3.11.3, 3.11.4 | 3.11.4 |
+
+The default pinned version is **1.8.10**: the 1.x line is the closest match to
+the mongo-local-cli model (two users, one database scoped app user, a REPL).
+
+InfluxDB’s lines are **not** data-compatible. Changing the version within a line
+is fine; changing the line (1.x ↔ 2.x ↔ 3.x) is refused once the instance has
+data — create a new instance instead.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `versions` | List every installable InfluxDB version (grouped by line). `-f/--flavor 1\|2\|3`, `-j/--json`. |
+| `create [name]` | Create a stopped instance with a pinned version + credentials (`-v/--influxdb`, `--port`, `--host`, `--database`, `--measurement`, `--org`, `--admin-user`, `--app-user`, `--admin-password`, `--app-password`); interactive wizard on a terminal. |
+| `setup [name]` (alias `bootstrap`) | Install the pinned version if missing, provision credentials/database, start the server. Repairs a running instance **online** (no restart) when its credentials are valid. |
+| `start [name]` | Start the daemon (auto-installs the pinned version when missing). |
+| `stop [name]` | Graceful stop (`-f/--force` to kill). |
+| `restart [name]` | Stop + start. |
+| `status [name]` (alias `ps`) | Health, flavors, running version, measurements, DSNs. `-j/--json`, `-s/--show-secrets`. |
+| `list` (alias `ls`) | All instances with state/version/port. `-j/--json`. |
+| `rename <name> <newName>` | Rename an instance (must be stopped first). |
+| `clone <name> <newName>` (alias `duplicate`) | Copy config + credentials to a new name (`-p/--port` optional; next free port by default). |
+| `set-password <name>` | Set an explicit password (`--user admin\|app`, `-p/--password`). 1.x applies live; 2.x only for the operator user. |
+| `users [name]` | List users/tokens (managed + server-side) with their scopes. |
+| `user-add <name> <username>` | Create a user (`-p/--password`, 1.x: `--db admin\|database`, `--privileges read,write,all`). |
+| `user-password <name> <username>` | Set a user's password (`-p/--password`). |
+| `user-rm <name> <username>` | Delete a user; the managed users are protected. |
+| `rotate [name]` | Rotate the managed secrets on the running server and verify them (`--admin` / `--app`). |
+| `query [name] [statement]` | One statement: InfluxQL (1.x), Flux (2.x), SQL (3.x). Reads stdin when omitted. `--admin` uses the admin credential. |
+| `logs [name]` | Server log tail (`-f` to follow, `-n/--lines`). |
+| `shell [name]` | Authenticated 1.x `influx` REPL (append args after `--`). `--admin` for the admin user. |
+| `install [name]` | Install the pinned version through mise (idempotent). |
+| `config show [name]` / `config set <name> <key> <value>` | View/edit configuration. |
+| `doctor [name]` | Environment + instance diagnostics. `-j/--json`. |
+| `web` | Start the web dashboard (`-H/--host`, `-p/--port`, `-t/--token`). |
+| `destroy [name]` (alias `rm`) | Stop and delete ALL instance data (`-y/--yes` for scripts). |
+
+Every instance-targeting command accepts either a positional name
+(`influx-local status my_app`) or `-n/--instance my_app`.
+
+When you run a command without a name and have several instances, an
+interactive picker (↑/↓ + Enter) asks which one to use. One instance → it is
+used directly; none → `default`. Non-interactive shells fall back to `default`.
+
+### Config keys
+
+`version` (pinned InfluxDB version), `port`, `host` (bind IP), `database`
+(1.x/3.x database, 2.x bucket), `measurement` (1.x/3.x sample measurement),
+`org` (2.x), `adminUser`, `appUser` (1.x), `publicHost` (advertised in DSNs).
+
+## Connection details
+
+`status` prints DSNs with masked secrets by default (secrets never land in your
+terminal/logs unless you pass `--show-secrets`):
+
+| Line | App DSN | Admin DSN |
+| --- | --- | --- |
+| 1.x | `influxdb://app:<pw>@127.0.0.1:8086/<db>` | `influxdb://admin:<pw>@127.0.0.1:8086` |
+| 2.x | `influxdb2://<app-token>@127.0.0.1:8086?org=<org>&bucket=<db>` | `influxdb2://<all-access-token>@127.0.0.1:8086?org=<org>` |
+| 3.x | `influxdb3://<admin-token>@127.0.0.1:8181/<db>` | — (the token is the credential) |
+
+The `influxdb*://` scheme is this tool's display format (InfluxDB itself has no
+DSN scheme); the endpoint, user/token, database/bucket/org in it are exactly
+what a client needs.
+
+## What maps to what
+
+If you are porting an app from mongo-local-cli, the concepts line up like this:
+
+| mongo-local-cli | InfluxDB 1.x | InfluxDB 2.x | InfluxDB 3 Core |
+| --- | --- | --- | --- |
+| `mongosh` REPL | `shell` (`influx`) | — (use `query`) | — (use `query`) |
+| admin user (`root`) | `admin` (`ALL PRIVILEGES`) | operator user | admin token |
+| app user (`readWrite`) | `app` (`ALL` on one database) | bucket-scoped token | — |
+| database | database | bucket | database |
+| collection | measurement | measurement | table |
+| password rotation | `SET PASSWORD` | token re-issue | not possible (see below) |
+
+## Web dashboard
+
+```bash
+influx-local web
+# → http://127.0.0.1:8788
+```
+
+Expose it on your LAN with a token — the panel can start/stop instances, rotate
+secrets and destroy data, so a non-loopback bind **requires** `--token`
+(refused otherwise):
+
+```bash
+influx-local web --host 0.0.0.0 --port 8788 --token <secret>
+```
+
+The “+ New” dialog contains the version picker (grouped by line, with the auth
+model and default port shown), so instances can be created with the right
+InfluxDB version straight from the browser. Operations run one at a time;
+progress streams into the operation log.
+
+## How it works / storage
+
+- Config per instance: `~/.influx-local/instances/<name>/config.json`
+- Toolchain per instance: `~/.influx-local/instances/<name>/.mise.toml`
+  (pins the version and the exact tarball URL)
+- Data: `~/.influx-local/instances/<name>/data/`
+- Secrets: `~/.influx-local/instances/<name>/creds.env` (0600)
+- Daemon pid / logs: `<influxd|influxdb3>.pid`, `<influxd|influxdb3>.log`
+- 2.x CLI client config is kept inside the instance dir
+  (`influx-cli-configs`), never in `~/.influxdbv2`.
+- `influx-local web` shares the same storage, so CLI and web interoperate.
+- Override the base dir with `INFLUX_LOCAL_HOME` and the mise executable with
+  `INFLUX_LOCAL_MISE` (used by the test suite).
+
+### Why mise needs a custom tool declaration
+
+InfluxData publishes server tarballs on `dl.influxdata.com`; the GitHub releases
+for these tags carry **no assets**, so mise's `github:`/`ubi` backends cannot
+install `influxd`. Each instance therefore carries a tiny `.mise.toml` that
+declares a generic `http:` tool with the versioned URL, e.g.:
+
+```toml
+[tools]
+"http:influxdb-1x" = { version = "1.8.10", url = "https://dl.influxdata.com/influxdb/releases/influxdb-{{ version }}_linux_amd64.tar.gz", strip_components = "1", bin_path = "usr/bin" }
+```
+
+`setup`/`install` run `mise install` against that file and resolve the resulting
+binaries through `mise where`, so several versions can be installed side by side.
+Every mise call is made with `MISE_CEILING_PATHS`/`MISE_TRUSTED_CONFIG_PATHS`
+set to the instance directory: mise otherwise walks *up* the tree and aborts with
+`Config files ... are not trusted` as soon as an unrelated `.mise.toml` exists in
+`$HOME` (or any parent), and it would also silently pick up a project toolchain
+that has nothing to do with this instance.
+
+### Per-line provisioning
+
+- **1.x** — users can only be created while authentication is off, so `setup`
+  starts a short-lived unauthenticated server bound to `127.0.0.1`, runs the
+  InfluxQL `CREATE USER`/`GRANT`/`CREATE DATABASE` statements, then restarts
+  with `auth-enabled = true`.
+- **2.x** — there is no unauthenticated window: `influx setup` is the only way
+  in and is refused once the instance is onboarded. Credentials are an operator
+  user + all-access token plus a bucket-scoped app token; a missing app token is
+  re-issued (and stale ones deleted) on every `setup`.
+- **3.x** — a single binary (`influxdb3 serve`). The admin token is minted once
+  by the server, so it is written to `creds.env` and reused; the database and
+  the initial table are created afterwards.
+
+## Known limitations
+
+- **3 Core tokens cannot be rotated in place.** InfluxDB refuses to create a
+  second `_admin` token, and starting the server with `--without-auth` disables
+  the token endpoints (HTTP 405). `rotate` therefore refuses for 3.x and tells
+  you to recreate the instance. 1.x and 2.x rotate normally.
+- **2.x `set-password --user app`** is refused: 2.x scopes access with tokens,
+  not users. Use `rotate --app` to replace the app token instead.
+- **1.x passes passwords as CLI flags** (`influx -username … -password …`),
+  which is visible to other local users via `ps` — the same exposure
+  mongo-local-cli has with its `mongosh` connection URIs. The 1.x CLI has no
+  environment-variable equivalent.
+- No user management on 3.x (tokens only), and `shell` exists only for 1.x
+  (2.x and 3.x CLIs have no REPL) — use `query`.
+- 1.8.10 is the last upstream 1.x OSS release; the 1.x line is supported here
+  because it maps most directly onto the classic user/role model.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+The unit tests cover the version catalog (URL/bin-path per line, catalog
+integrity) and the credential schema; they need no network and no InfluxDB
+install. For an end-to-end check, create an instance and run `setup` — that is
+the path CI cannot cover without downloading InfluxDB.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+`web/style.css` is reused from [mongo-local-cli](https://www.npmjs.com/package/mongo-local-cli)
+(MIT), which this tool models its UX on.

package/bin/influx-local.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../src/cli');
+run(process.argv);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "influx-local-cli",
+  "version": "0.1.0",
+  "description": "Create, start and manage local InfluxDB instances (1.x / 2.x / 3.x) without Docker/Podman. CLI + Web dashboard, powered by mise.",
+  "keywords": [
+    "influxdb",
+    "influx",
+    "local",
+    "cli",
+    "web",
+    "database",
+    "time-series",
+    "influxql",
+    "flux",
+    "mise",
+    "without-docker",
+    "development"
+  ],
+  "license": "MIT",
+  "bin": {
+    "influx-local": "bin/influx-local.js"
+  },
+  "main": "src/manager.js",
+  "files": [
+    "bin",
+    "src",
+    "web",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/catalog.test.js test/creds.test.js",
+    "start": "node bin/influx-local.js web"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "express": "^4.21.2"
+  }
+}