memtrace connectEnterprise

Connect an organization member to self-hosted MemDB, or use a manual credential for bootstrap and offline setups.

Usage#

The normal enterprise form is memtrace connect <organization-slug>. It uses the account from memtrace auth login, verifies current organization membership, obtains a signed enrollment assertion, and asks the self-hosted MemDB to create an expiring local bearer. It then writes secretless .memtrace/team.toml and stores the bearer in the user's config directory. The command also accepts the engineer half of a provisioning bundle — a bare connect.json or a .tar/.tar.gz bundle — or plain --endpoint/--database/--org flags, authenticates your license, writes a committable, secretless .memtrace/team.toml at the workspace root, stores any MemDB access token per-endpoint in ~/.config/memtrace/credentials.json, and probes the endpoint. Afterwards, memtrace start boots in external mode with zero environment variables required.

Inputs: bundle, connect.json, or flags#

A bare positional value that is not a file path is treated as an organization slug. File inputs accept these shapes, sniffed by content rather than only by extension:

• A bare connect.json file (detected by a leading {).
• An uncompressed .tar bundle, or a gzipped .tar.gz (detected by gzip magic bytes; decompression is capped at 64 MiB). Either way, the tarball must contain engineer/connect.json. To connect the owner, pass the extracted bare cluster/owner-connect.json file instead; full-bundle extraction deliberately selects the non-admin engineer file.
• No positional at all — supply --endpoint, --database, and --org directly.

Flags always override values from the file. An endpoint is mandatory from one source or the other, and must start with http:// or https://. If a bundle was built before its cluster URL was pinned, its endpoint is still the literal placeholder {{MEMDB_ENDPOINT}} — connect rejects that and asks you to pass --endpoint explicitly. Database defaults to memtrace if neither the flag nor the file supplies one.

A full MTC- license key in a connection file is authoritative and replaces an older community session. Without one, connect reuses valid stored credentials or MEMTRACE_LICENSE_KEY, then falls back to the interactive browser device flow — the same waiting-room machinery as memtrace auth login.

What it writes#

.memtrace/team.toml, anchored at the workspace root (a workspace-root override, else the git root, else the current directory — not necessarily your cwd), is secretless by construction: only endpoint, database, tls_ca, and org_slug are ever rendered. The connection file's license_key_ref and optional memdb_token are treated as secrets and are never written to team.toml or printed. Because it carries no secrets, team.toml is meant to be committed to your repo so every teammate who clones it gets the same external MemDB pointed at automatically.

The MemDB access token itself is stored separately, in ~/.config/memtrace/credentials.json, under a per-endpoint memdb_tokens map — never in team.toml. Organization-enrolled tokens also carry a local expiry and renew during startup within their final hour. Manual-token precedence is --token, MEMTRACE_MEMDB_AUTH_TOKEN, a bearer embedded in the connection file, then a previously stored token. When MemDB rejects a bearer, connect exits nonzero and keeps the written configuration so the user can sign in and retry.

Flags#

Environment variables#

--status and --disconnect#

memtrace connect --status never mutates anything. It prints: whether team.toml is present; the effective mode and its provenance (explicit env var, implied by team.toml, inferred from an endpoint env var, or default); endpoint, database, org, and TLS CA; whether a token is present (never the value itself); the per-machine daemon owner-lock state; and a live connectivity probe. It always exits 0, even when the endpoint is unreachable.

memtrace connect --disconnect removes .memtrace/team.toml (reading its endpoint first if --endpoint wasn't given) and scrubs the stored MemDB token for that endpoint from credentials.json. It explicitly leaves your license credentials untouched — for that, use memtrace auth logout. It's idempotent: a missing team.toml just prints "already disconnected".

After connecting#

Exit behavior on a normal (non --status/--disconnect) run: a reachable server prints a success summary — endpoint, database, org, edition, token status, team file path, and a Next: memtrace start hint — and exits 0. A reachable server that rejects the bearer exits nonzero: configuration was saved, but memtrace start cannot work until the member signs in and reconnects, or an administrator uses the manual fallback. An unreachable endpoint also exits nonzero. In both cases team.toml is deliberately kept so a later connect or --status can retry.

Once connected, run memtrace start in the same workspace: it reads .memtrace/team.toml, boots in external mode with zero environment variables, and connects straight to your self-hosted MemDB instead of spawning a local sidecar.

Gotchas#

Examples#

$ memtrace auth login
$ memtrace connect acme
# Verifies membership and enrolls a local expiring MemDB credential.

$ memtrace connect cluster/owner-connect.json
# Owner-only bootstrap/recovery: stores the admin bearer locally.

$ memtrace access add alice@example.com --role writer --out alice.connect.json
# Manual/offline fallback: admin creates a user-specific connection file.

$ memtrace connect alice.connect.json
# Manual/offline user stores the embedded bearer,
# writes secretless .memtrace/team.toml, and pings the server.

$ memtrace connect --endpoint https://memdb.corp.example:50051 --database corp --org acme
# Flags-only connect, no bundle; database defaults to `memtrace` if omitted.

$ memtrace connect bundle.tar.gz --endpoint https://memdb.corp.example:50051
# Needed when the bundle predates the cluster URL being pinned
# and still carries the {{MEMDB_ENDPOINT}} placeholder.

$ memtrace connect --endpoint https://memdb.corp.example:50051 --token mdb-abc123
# Compatibility/manual path. Prefer an administrator-generated connection file.

$ memtrace connect --offline-license license.mtl
# Air-gapped install: verify and install a signed offline license, then exit
# (add --endpoint/bundle args to continue into the connect flow).

$ memtrace connect --status
# Show effective config, mode provenance, token presence, and a live
# connectivity probe. Changes nothing.

$ memtrace connect --disconnect
# Remove .memtrace/team.toml and scrub the stored token for that endpoint.
# License credentials stay — use `memtrace auth logout` for those.

See also Enterprise: connect, memtrace access, memtrace auth, memtrace status, and memtrace start.