enbox docs
Packages

@enbox/cli

CLI-first Enbox entrypoint for app APIs, auth, and relay/PIN wallet connect.

@enbox/cli is the terminal-focused package for Enbox apps. It re-exports the main app API from @enbox/api, auth/session helpers from @enbox/auth, and a Node/Bun-only connect handler for wallet approvals.

Installation

bun add @enbox/cli

Usage

import {
  CliConnectHandler,
  createConnectionStore,
  defineApplicationManifest,
  defineProtocol,
  recordCodecs,
} from '@enbox/cli';

const NotesDefinition = {
  protocol  : 'https://example.com/protocols/notes',
  published : true,
  types     : {
    note: {
      schema      : 'https://example.com/schemas/note',
      dataFormats : ['application/json'],
    },
  },
  structure: {
    note: {},
  },
} as const;

const NotesProtocol = defineProtocol(NotesDefinition, {
  note: recordCodecs.json<{ body: string }>(),
});

const application = defineApplicationManifest({
  protocols: [{ protocol: NotesProtocol, permissions: ['write'] }],
} as const);
const store = createConnectionStore({
  application,
  connectHandler: CliConnectHandler({
    appName          : 'Notes CLI',
    connectServerUrl : 'https://your-dwn.example/connect',
  }),
});

let snapshot = await store.initialize();
if (snapshot.phase === 'disconnected') {
  snapshot = await store.connect();
}
if (snapshot.phase !== 'connected') {
  throw snapshot.error ?? new Error('Connection was not established.');
}

await snapshot.enbox.using(NotesProtocol).records.create('note', {
  data: { body: `Connected as ${snapshot.session.did}` },
});

await store.disconnect();
await store.dispose();

The handler uses the encrypted relay flow. It prints a terminal QR code and wallet link by default, prompts for the wallet-displayed PIN, then returns the delegated session through the connection-store lifecycle.

When connectServerUrl is omitted, the handler resolves the relay from connectServerUrlProvider, then from the wallet origin's /.well-known/enbox-connect document ({ "connectServerUrl": "https://dwn.example/connect" }), then prompts. Sessions request a one-hour TTL by default; wallets may clamp it.

Set openBrowser: true for same-machine flows that should open the wallet approval link in the local default browser instead of printing a QR code.

Key exports

ExportDescription
EnboxHigh-level app API from @enbox/api
createConnectionStore()Application connection lifecycle and observable snapshots
defineProtocol()Type-safe protocol definition helper
recordCodecsJSON, text, bytes, and Blob record codecs
AuthManagerAuth/session lifecycle from @enbox/auth
CliConnectHandlerTerminal relay/PIN wallet connect handler

On this page