Auralogger for Node.js (SDK + CLI)

Stream logs from your Node server and your browser app to Auralogger, then query them from the terminal , while watching them popup on ur mobile/browser with Aura

Same deal as the terminal output: we dress up the prose; commands, env names, and tables are the contract. Copy those exactly. The jokes are optional.

---

Quick start (copy/paste)

Run CLI commands from the directory that contains your .env / .env.local (or where AURALOGGER_PROJECT_* is set in your shell/CI). The CLI loads .env files from the current working directory — i.e. cd into the app before you heroically type npx.

Prefer npx so the CLI runs in this project’s context with the version you expect — Auralogger is project-scoped (tokens + publishable ids per app), not a “install once globally and forget which repo you’re in” kind of tool.

Migrating: rename **AURALOGGER_PROJECT_SECRET** → **AURALOGGER_PROJECT_TOKEN** and add **AURALOGGER_USER_SECRET**. There is no backward-compatible read of the old env name.

1) Add the package

npm install auralogger-cli

and you can look up commands at

npx auralogger-cli --help

2) Run init (private creds + client snippet)

Origin story time: you’ll get private credentials from https://auralogger.com, paste them here and you get two snippets — Auralog (browser: project token only + internal proj_auth; never user secret) and AuraLog (server: token + user secret). Different files, different job descriptions.

Run this in your app repo (where your .env should live):

npx auralogger-cli init

After **npm install auralogger-cli** in this repo, npx can run the local CLI binary by name (same tool, pinned to your lockfile):

npx auralogger init

**auralogger init** opens with a short banner, prompts for any missing creds, then shows the current session from proj_auth and a five-line-style copy-paste block when values are new: AURALOGGER_PROJECT_TOKEN, AURALOGGER_USER_SECRET, AURALOGGER_PROJECT_SESSION, NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN, and VITE_AURALOGGER_PROJECT_TOKEN (the last two match the server token). It does not print project id or styles into .env — those hydrate via proj_auth. Then two snippets in different files: **Auralog** and **AuraLog**. Variable details: **[user-docs/environment.md](user-docs/environment.md)**.

3) Sanity-check connectivity

Before you wire helpers everywhere: confirm the pipes actually connect. Less “mystery meat,” more “we tested this lane.”

npx auralogger-cli server-check
npx auralogger-cli client-check

After **npm install** in this project:

npx auralogger server-check
npx auralogger client-check

**client-check** resolves the same project/session context as **server-check**, but opens **create_browser_logs** with no auth header, like **AuraClient** in the browser.

4) Send logs from code

Run **auralogger init** and paste what it prints, or copy the shapes below. **Auralog** is for the browser; **AuraLog** is for Node — put each in its own file (or repo). Same energy as the CLI banner: two helpers, two files — don’t cross the streams.

Which file is which?

• 🎨 Browser / frontend — React, Vue, Vite, Next client code, anything bundled for the user. **AuraClient** streams logs over the WebSocket to Auralogger; it does not print successful logs to the browser console (only errors / connection issues). Project token only in this file — never AURALOGGER_USER_SECRET.
• 🧱 Server / backend / CLI — HTTP APIs, workers, cron jobs, this CLI, anything that runs on a machine you control, not in the user’s browser. Private creds live only in this copy — server suit only.

Client-side Auralog (auralogger-cli/client) — save as e.g. src/lib/auralog/client-auralog.ts. Set **NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN** in .env.local; AuraClient derives project id/session/styles via POST /api/{project_token}/proj_auth (token in the URL path).

import { AuraClient } from "auralogger-cli/client";

export type AuralogParams = {
  type: string;
  message: string;
  location?: string;
  data?: unknown;
};

let configured = false;

function ensureConfigured(): void {
  if (configured) return;

  // AuraClient only needs a project token; proj_auth uses POST /api/{token}/proj_auth (token in path).
  // You can also use hardcoded strings instead of env lookups below (avoid committing real values).
  const projectToken = process.env.NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN;
  if (!projectToken) {
    throw new Error("Missing NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN");
  }

  AuraClient.configure( projectToken );
  configured = true;
}

/** Browser-safe: project token only. Never include user secret in client bundles. */
export function Auralog(params: AuralogParams): void {
  ensureConfigured();
  AuraClient.log(params.type, params.message, params.location, params.data);
}

Use it from a client component or page:

import { Auralog } from "@/lib/auralog/client-auralog";

Auralog({
  type: "info",
  message: "new client tests",
  location: "src/app/test/page.tsx",
  data: { source: "test-page-client" },
});

Server-side AuraLog (auralogger-cli/server) — save as e.g. src/lib/auralog/server-auralog.ts. Never import this file from client code.

import { AuraServer } from "auralogger-cli/server";

export type AuralogParams = {
  type: string;
  message: string;
  location?: string;
  data?: unknown;
};

let configured = false;

function ensureConfigured(): void {
  if (configured) return;

  // You can also pass string literals to AuraServer.configure(...) instead of process.env (never commit real secrets).
  const projectToken = process.env.AURALOGGER_PROJECT_TOKEN;
  if (!projectToken) {
    throw new Error("Missing AURALOGGER_PROJECT_TOKEN");
  }
  const userSecret = process.env.AURALOGGER_USER_SECRET;
  if (!userSecret) {
    throw new Error("Missing AURALOGGER_USER_SECRET");
  }

  AuraServer.configure(projectToken, userSecret);
  configured = true;
}

/** Server-only: uses project token + user secret from env. Do not import from client components. */
export function AuraLog(params: AuralogParams): void {
  ensureConfigured();
  AuraServer.log(params.type, params.message, params.location, params.data);
}

Use it from a route handler, server action, etc.:

import { AuraLog } from "@/lib/auralog/server-auralog";

AuraLog({
  type: "info",
  message: "new server tests",
  location: "src/app/api/test/auralog/route.ts",
  data: { source: "test-api-route" },
});

5) Fetch logs in your terminal

You shipped logs from code; now steal them back for debugging with a filter-shaped crowbar.

npx auralogger-cli get-logs -maxcount 20

After **npm install** in this project:

npx auralogger get-logs -maxcount 20

One page per command: each get-logs run sends a single POST /api/{project_token}/logs (header **secret** = user secret; some backends also require **user_secret**, and the CLI sends both) and prints whatever comes back in that response — there is no automatic multi-request paging inside the CLI. Use **-maxcount** (the CLI caps it at 100 per request) and **-skip** to move through results: run again with a higher skip, or wrap calls in a small script if you need many pages. Narrow filters (e.g. **-time**) keep each page meaningful.

Full command list and filter syntax: **[user-docs/commands.md](user-docs/commands.md)**.

---

What to import (avoid bundler pain)

Pick the right door: **/server* vs **/client**. Wrong door = surprise ws in the browser bundle and a very angry webpack.*

• Server code: import { AuraServer } from "auralogger-cli/server"
• Browser code: import { AuraClient } from "auralogger-cli/client"

Using the explicit subpaths avoids accidentally pulling Node-only dependencies (like ws) into client bundles. The package exports field maps **auralogger-cli/server** to a stub on **browser** builds.

Fire-and-forget: AuraServer.log / AuraClient.log (and the **Auralog** / **AuraLog** helpers) return immediately; work is scheduled on the next tick. Neither mirrors successful logs to the local console — only problems (missing config, proj_auth / WebSocket / send failures) use console.error / console.warn. Idle sockets close after a quiet period; call AuraServer.closeSocket() / AuraClient.closeSocket() for a clean shutdown. On Node you can call AuraServer.configure(projectToken, userSecret) or await AuraServer.syncFromSecret(projectToken, userSecret) yourself if you skip the helper.

---

Debugging (most common issues)

When the happy path ghosts you — start here. Facts first, feelings later.

AuraServer doesn’t stream

Usually: the token or user secret never made it in, or **proj_auth* didn’t get a word in.*

• The process needs **AURALOGGER_PROJECT_TOKEN** and **AURALOGGER_USER_SECRET** (or explicit AuraServer.configure(projectToken, userSecret) / syncFromSecret). Id, session, and styles are loaded via **POST /api/{project_token}/proj_auth** after configure (token URL-encoded in the path; no secret header on that route).

If private creds are missing or proj_auth fails, **AuraServer.log does not stream** to the backend. You may see a one-time console.error about incomplete configuration, or **console.error** when a send or socket fails — not a per-log local print on success.

Client bundle includes ws (or crashes on process, fs, etc.)

You invited the server entry to a client party. Bouncers hate that.

• Use the client-only entry:

import { AuraClient } from "auralogger-cli/client";

AuraClient says WebSocket is not available (Node)

Browsers were born with **WebSocket*. Older Node sometimes wasn’t — polyfill or upgrade, your call.*

AuraClient.log uses the runtime’s **global WebSocket**. It works in browsers and in Node versions that provide a global WebSocket (Node 22+).
If you must run AuraClient in older Node, set globalThis.WebSocket (see **user-docs/**).

Detailed reference

Below is the same reference material as **user-docs/*, inlined for one-stop reading. Tables and spelling are law — skim the flavor, obey the facts.*

Environment variables

Two buckets: private credentials (project token + user secret), three publishable knobs. Mix them up and the multiverse gets weird.

Two classes of values:

• Private / auth — **AURALOGGER_PROJECT_TOKEN** and **AURALOGGER_USER_SECRET**.
  • Project token is in the path for **proj_auth**, **/{proj_token}/create_log**, and **/{proj_token}/create_browser_logs**.
  • User secret is **Authorization: Bearer …** on server **/{proj_token}/create_log** only (**AuraServer** / **server-check**). Never expose **AURALOGGER_USER_SECRET** in browser bundles, public repos, or NEXT_PUBLIC_* / VITE_* keys.
• Publishable — **project_id, **session, and **styles** (the three non-secret fields from auralogger init). They are not API secrets. You still choose where they live: server-only .env vs client-visible env keys for frontends.

The CLI and **AuraServer** need both private creds for server-side operations. **AuraClient** uses a project token only and hydrates id/session/styles via proj_auth; it never reads **AURALOGGER_USER_SECRET**.

Private variable (exact name)

Variable	Who uses it	Notes
AURALOGGER_PROJECT_TOKEN	CLI (init, get-logs, checks), **AuraServer, **AuraClient input	Path segment for proj_auth, **/api/{proj_token}/logs** (get-logs), **/{proj_token}/create_log**, **/{proj_token}/create_browser_logs**. CLI also accepts the same value as **NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN** or **VITE_AURALOGGER_PROJECT_TOKEN**.
AURALOGGER_USER_SECRET	CLI (init, get-logs, checks), **AuraServer**, **server-check**	Server-side / CI secrets only. Authorization: Bearer … on **/{proj_token}/create_log; **get-logs** sends it as header **secret** on **POST /api/{project_token}/logs**. Never exposed to **AuraClient.

Publishable variables (exact base names)

These identify the project and style logs. They are not private credentials.

Role	Primary env keys (Node / server .env)	In client bundles (must be exposed by the framework)
Project id	AURALOGGER_PROJECT_ID	NEXT_PUBLIC_AURALOGGER_PROJECT_ID (Next.js) or VITE_AURALOGGER_PROJECT_ID (Vite); unprefixed still works on server
Session	AURALOGGER_PROJECT_SESSION	NEXT_PUBLIC_AURALOGGER_PROJECT_SESSION or VITE_AURALOGGER_PROJECT_SESSION
Styles (single-line JSON array)	AURALOGGER_PROJECT_STYLES	NEXT_PUBLIC_AURALOGGER_PROJECT_STYLES or VITE_AURALOGGER_PROJECT_STYLES

Resolution order for each publishable field is: **NEXT_PUBLIC_*, then **VITE_*, then unprefixed AURALOGGER_PROJECT_*. **auralogger init** prints session plus the three project-token spellings and user secret (see quick start above); id/styles for CLI styling can still be set manually or fetched per command via proj_auth.

Who loads what

**AuraClient (browser):** project token only — usually **NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN** / **VITE_...** passed into **AuraClient.configure**. Id/session/styles come from **proj_auth** in memory. No .env file reads in the browser. The publishable id/session/styles env keys remain useful for **init** output, **AuraServer**, and CLI; they are not required on the client for **AuraClient**.

**AuraServer (Node):** reads **process.env; on first AuraServer.log or syncFromSecret it may once load **.env and **.env.local** from **process.cwd()** (Node only). Private creds must only exist in environments you treat as private.

CLI: loads **.env** / **.env.local** from cwd before each command.

Getting values

The boring-but-correct pipeline — same beats **init* walks you through in the terminal.*

1. Run **auralogger init** — banner first, then prompts for whatever is missing.
2. If the project token (**AURALOGGER_PROJECT_TOKEN** / **NEXT_PUBLIC_** / **VITE_**), **AURALOGGER_USER_SECRET**, or **AURALOGGER_PROJECT_SESSION** is unset, the CLI prompts or fetches as needed.
3. After proj_auth, it shows the live session, the up-to-five-line dotenv block (token server + Next + Vite, user secret, session — each omitted if already in env), then two snippets (separate files): **Auralog** vs **AuraLog**.
4. Put private creds in server-side env (.env gitignored, host secret store, CI secrets). For **AuraClient, use **NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN** or **VITE_AURALOGGER_PROJECT_TOKEN** (same ciphertext as the server token). Project id and styles need not live in .env; SDKs and **get-logs can pull them from proj_auth when needed (styles affect **get-logs** terminal output, not local SDK success logging).

**await AuraServer.syncFromSecret(projectToken, userSecret)** (Node) can fill id, session, and styles in memory from the API without storing them in .env.

Example layout (fake values)

Toy values — swap for what **auralogger init* shows you. Real **STYLES** strings are long; don’t hand-craft them unless you enjoy pain.*

Typical .env fragment (Next + Vite token lines are for bundlers; keep user secret off the client):

# PRIVATE — never expose to browser bundles or public repos
AURALOGGER_PROJECT_TOKEN="your-project-token"
AURALOGGER_USER_SECRET="your-user-secret"

AURALOGGER_PROJECT_SESSION="session-token-here"
NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN="your-project-token"
VITE_AURALOGGER_PROJECT_TOKEN="your-project-token"

(**auralogger init** prints this shape when all values are new.) Optional: add **NEXT_PUBLIC_ / VITE_ / unprefixed** id + styles keys if you want static styling in the CLI without a proj_auth fetch on every get-logs.

Commands vs runtime

Context	Private creds	Publishable three
**auralogger init**	Optional in env, else prompt	Banner → prompts → session line + up to five dotenv lines (token ×3 + secret + session) after proj_auth
**auralogger server-check**	Token + user secret in env (or paste when prompted)	CLI fetches project id + session via proj_auth before opening the socket (session/styles not required in .env)
**auralogger client-check**	Token + user secret in env (or paste when prompted)	Same proj_auth context as **server-check**; opens **/{proj_token}/create_browser_logs** (path-only); session in payload; no user secret on the socket
**auralogger get-logs**	Token + user secret in env or at prompt	**STYLES** optional in env: if unset, CLI fetches them via **proj_auth** for this run
**AuraServer**	Required (configure / env / syncFromSecret)	Loaded from **proj_auth** after token auth (publishable trio not required in .env)
**AuraClient**	Browser: project token only; never user secret	Id/session/styles auto-hydrated via proj_auth

Environment troubleshooting

Quick triage — most “it worked on my machine” stories start with cwd or a mangled JSON string.

• **server-check / variable missing** — Run from the directory that contains your .env, or export vars in the shell (process.cwd()).
• Styles errors — Value must be valid JSON array string; fix the env value or unset it so **get-logs** can pull styles from **proj_auth**.
• **AuraServer not streaming** — Ensure **AURALOGGER_PROJECT_TOKEN** and **AURALOGGER_USER_SECRET** (or call **syncFromSecret / configure) so auth + ingest can run; proj_auth uses the token in the URL path. Successful logs are not printed locally; misconfiguration may surface as **console.error.
• Client bundle + ws — Use **auralogger-cli/client**; the package maps **./server** to a browser stub so ws is not pulled in for AuraServer imports on the client.

Advanced overrides (contributors / self-hosted backends)

HTTP and WebSocket base URL overrides are documented for maintainers in **dev-docs/routes.md** (not required for normal use of hosted Auralogger).

CLI command reference

The deputized cheat sheet: subcommands in a table, **get-logs* grammar spelled out, examples you can steal.*

The full getting started story (install, auralogger.com, environment variables, and code examples) is earlier in this README. Variable details are in Environment variables above.

This section is the command cheat sheet for quick lookup.

Invocation

auralogger <command> [arguments...]

Commands (no flags except filter tokens on get-logs)

Command	Args	Purpose
init	—	Banner, then prompts; POST /api/{project_token}/proj_auth (token in path); copy-paste dotenv up to five lines (AURALOGGER_PROJECT_TOKEN, AURALOGGER_USER_SECRET, AURALOGGER_PROJECT_SESSION, NEXT_PUBLIC_AURALOGGER_PROJECT_TOKEN, VITE_AURALOGGER_PROJECT_TOKEN — omissions + notes if already in env); two snippets (**Auralog** + **AuraLog**).
server-check	—	Test the server WebSocket pipe. Uses AURALOGGER_PROJECT_TOKEN + AURALOGGER_USER_SECRET (env or prompt), fetches project id + session via proj_auth, then opens /{proj_token}/create_log with Authorization: Bearer ... and sends one log.
client-check	—	Test the client-style pipe. Uses the same token/secret + proj_auth context as **server-check**, then opens /{proj_token}/create_browser_logs (no auth header on the socket, like **AuraClient**) and sends one log with the resolved session.
test-serverlog	—	Send 5 logs via AuraServer.log (production path), then close.
test-clientlog	—	Send 5 logs via AuraClient.log (production path), then close.
get-logs	[filters...]	Fetch and print logs; filters use grammar below. If **AURALOGGER_PROJECT_STYLES** (or public equivalents) is missing, runs the same **proj_auth** fetch as **init** and styles logs from the response (prompts for token/user secret when needed).

get-logs filter grammar

Filters look like CLI flags but speak JSON — numbers for **maxcount* / **skip**, arrays almost everywhere else.*

Paging model: one CLI invocation → one HTTP request → one logs array. Pagination is manual: combine **-maxcount** (max 100 enforced in the CLI before the request) and **-skip** across separate runs (or a loop in a script). The server is expected to honor those filters when building the response.

-<field> [--<operator>] <json-value>

• **maxcount**, **skip**: value is a JSON number.
• All other fields: value is a JSON array.

Fields

Field	Operators	Default op
type	in, not-in	in
message	contains, not-contains	contains
location	in, not-in	in
time	since, from-to	since
order	eq	eq
maxcount	eq	eq
skip	eq	eq
data.<path>	eq	eq

Examples

auralogger get-logs -type '["error","warn"]' -maxcount 50
auralogger get-logs -message '["timeout"]' -skip 20 -maxcount 30
auralogger get-logs -type --not-in '["info","debug"]' -time --since '["10m"]'
auralogger get-logs -data.userId '["06431f39-55e2-4289-80c8-5d0340a8b66e"]'

CLI and environment

See Environment variables above for required variables and how to inject them.

---

Contributing

Contributor context lives in **dev-docs/** (Git repo only). Documentation index: **docs/README.md** — capes optional, clear commits appreciated.

https://github.com/Beever-Labs/auralogger-node