@super-log/cloud

Connect a machine to super-log Cloud: enrolment, the uplink daemon, journal seeding — and reading the team's journal back from any editor or shell.

This is the proprietary half of super-log. The MIT project — the hub, the viewer and the forty-odd tailers — is a separate install and carries no cloud code at all. Nothing here is required to run super-log locally.

Source-published for audit, which is a different promise from open source and the one that actually matters for this tool: a program that decides what leaves your machine should be readable by the person whose machine it is. Everything it sends is printed by superlog-cloud explain; everything it stores is one 0600 JSON file you can cat.

One machine, several organisations (0.4.0)

A machine can publish the same hub journal to more than one organisation — a contractor's laptop feeding a client's bench and their own, a build box shared by two teams. The daemon always supported it (--url --token --bench --state are per process); only this wrapper assumed a single account.

superlog-cloud login            # the first organisation
superlog-cloud login --add      # and another, deliberately
superlog-cloud list             # every uplink: org, bench, service, cursor
superlog-cloud install          # one service per uplink, all of them
superlog-cloud logout --org <id or name>   # remove one
superlog-cloud logout --all                # remove them all
superlog-cloud token --org <id or name>    # the credential for one

A bare login on an enrolled machine is still refused. Adding a tenant is a decision, never the side effect of running the same command twice — that is how a machine quietly starts publishing into somebody else's organisation.

Each uplink keeps its own cursor (~/.superlog/uplink-cursor[-<org>].json) and its own service. Two uplinks sharing a cursor would each skip what the other had sent. The slot is stamped on the uplink when it is created and never recomputed from its position, because removing the first of two used to promote the survivor and silently move its cursor — which re-uploads whatever the hub still holds. test-uplinks.mjs pins that case by name.

Pausing is still per machine, not per organisation: superlog-cloud pause stops all of them. Half a machine going quiet during an incident is worse than all of it, and harder to notice.

The first enrolment keeps every name it had before 0.4.0 — same service label, same unit, same cursor file — so upgrading a machine that was enrolled last week changes nothing about it.

Install

npm install -g superlog-cloud

Or run it without installing anything:

npx superlog-cloud login

The package name is deliberately unscoped even though the sibling packages are @super-log/*. npx <pkg> runs the binary whose name matches the last segment of the package name; as @super-log/cloud that segment is cloud, there is no such binary, and npx fails with cloud: command not found. Unscoped, the segment is the binary name, and npx superlog-cloud login works with nothing installed — which is the whole point of offering it.

Requires Node 22 or newer — the uplink uses the global WebSocket that arrived in Node 22. Zero dependencies.

Connect a machine

Two entry points, same ceremony, because which end starts depends on which end the human is already holding.

From the machine (a server nobody is sitting at). It prints a code and a URL first, unconditionally, then waits:

superlog-cloud login

From the browser (you just signed up or paid, and the console showed you a code). The code is a one-time claim on a consent, not a credential — it is dead after redemption or fifteen minutes:

superlog-cloud login --code XXXX-XXXX

Then make the uplink a service — it starts now, at every boot or login, and after any crash, and no service file carries the token (the daemon reads ~/.superlog/cloud.json itself):

superlog-cloud install

| Platform | What install creates | Verified | | --- | --- | --- | | macOS | a LaunchAgent, ~/Library/LaunchAgents/com.super-log.uplink.plist (RunAtLoad, KeepAlive) | yes — this is how the first customer benches run | | Linux | a systemd user unit, ~/.config/systemd/user/superlog-uplink.service; --system (as root) writes /etc/systemd/system/superlog-uplink.service for a box nobody logs in to | written to the same shape; not yet run on a Linux box by us — tell us | | Windows | a Scheduled Task "super-log uplink" at logon, restarted if it stops | written; not yet run on Windows by us — tell us |

superlog-cloud status shows the service's state; superlog-cloud uninstall stops it and removes it. To run the daemon by hand instead, in one terminal:

secure-superlogd --url https://api.super-log.com --bench my-bench

The viewer's read credential. The open-source viewers' AI-interpretation panel signs in with a separate, read-only token in the same file:

superlog-cloud login --viewer

It prints a code to approve at app.super-log.com/device, then merges the token into ~/.superlog/cloud.json without touching the bench token. A plain login on a new machine already writes both.

Commands

| Command | What it does | | --- | --- | | superlog-cloud login | Device-code enrolment; prints a code and a URL, then polls | | superlog-cloud login --code XXXX-XXXX | Redeem a pre-approved code from the console | | superlog-cloud login --viewer | The viewer's read credential (an agent token), beside the bench's | | superlog-cloud install / uninstall | Run the uplink as a service (launchd / systemd / Scheduled Task) — or stop and remove it | | superlog-cloud status | Enrolled? which org, which bench, is the uplink up, is it paused | | superlog-cloud seed --journal DIR | Upload history this bench already has, so day one is not an empty room | | superlog-cloud pause / resume | Stop sending without unenrolling | | superlog-cloud logout | Remove the local credential | | superlog-cloud explain | The endpoint, the exact headers and payload, and what is never sent | | superlog-cloud token | Print the bench token, for scripts | | superlog-cloud logs | The org's saved logs, one event per line on stdout | | superlog-cloud streams | What is publishing, and how much | | superlog-cloud read | Ask the interpreter what happened; prints the reading | | superlog-cloud export | Everything the org holds, as NDJSON — the escape hatch, as a command | | secure-superlogd | The uplink daemon: forward a hub's firehose to the cloud |

Reading the journal from an editor

There is no plugin to install. These print to stdout and nothing else, which is the shape every editor already consumes — a command that fills a buffer:

superlog-cloud logs --since 2h --topic cpp.engine --grep PricingError
superlog-cloud logs --limit 500 | grep -i timeout | less
superlog-cloud read --audience executive
superlog-cloud export --since 7d --out journal.ndjson

| Editor | How | | --- | --- | | Vim / Neovim | :r !superlog-cloud logs --since 1h | | Emacs | M-x shell-command → superlog-cloud logs | | Helix, Kakoune, nano, anything | a pipe |

Diagnostics and the footer go to stderr, so a buffer fills with logs and not with commentary; --json is there for anything that would otherwise have to parse prose. Reading uses the viewer credential from login --viewer, never the bench token — a machine that streams logs has no business reading the organisation's journal back.

superlog-cloud login --url URL (or SUPERLOG_CLOUD_URL) points the whole thing at a staging deployment. With no flags it reaches production.

What it stores

• ~/.superlog/cloud.json — the bench credential, mode 0600. Never printed.
• ~/.superlog/cloud.paused — the stop tap. A file, not a socket and not a signal: the daemon accepts no inbound connection by design, and a file is the one control you can ls, set from any shell, and leave in place across a reboot.

Licence

Proprietary. See LICENSE.