Getting Started

Install the CLI, create a project, set values, seal a secret, and resolve config at runtime in ~10 minutes.

Prerequisites: Node.js 18+, an OrbSeal account at orbseal.com

---

Install

# No install needed — use npx directly:
npx @dotlabshq/orbseal --version

# Or install globally:
npm install -g @dotlabshq/orbseal

---

Log in

Grab your admin token from the dashboard under Settings → API Tokens:

npx orbseal login

Token (orb_admin_...): orb_admin_xxxx
✓ Logged in  https://api.orbseal.com

---

Full walkthrough

The rest of this guide builds a real example — TaskFlow — a task management app whose settings UI looks like this:

Settings
  ├── Appearance       theme, accent_color, language          → user scope
  ├── Notifications    email, push, digest_frequency          → user scope
  ├── Team             max_seats, allowed_domains             → workspace scope
  ├── Behavior         default_view, items_per_page, features → project scope
  └── Infrastructure   app_url, cdn_url, secrets              → environment scope

Every group maps directly to an orbseal scope. User preferences are per-user and overridable. Team settings are org-wide. Infrastructure and secrets are per environment.

---

Prerequisites

• Node.js 18+
• An orbseal account (orbseal.com) or a local deploy

---

1. Login

npx orbseal login

Token (orb_admin_...): orb_admin_xxxx
✓ Logged in  https://api.orbseal.com

---

2. Create a project

Slugs and short IDs are generated automatically from the name.

npx orbseal workspaces create "Platform"

✓ Workspace created: platform  (id: xzvdrg)

Set your active context so you don't have to repeat workspace/project in every command:

npx orbseal use acme/platform

✓ Context set to acme / platform
  Tip: run orbseal ls to see the full tree

npx orbseal projects create "TaskFlow"

✓ Project created: taskflow  (id: zdfmcs)  in platform

npx orbseal use acme/platform/taskflow
npx orbseal envs create "Production"
npx orbseal envs create "Staging"

✓ Environment created: production  in platform/taskflow
✓ Environment created: staging     in platform/taskflow

Check the tree:

npx orbseal ls

  ● acme  Acme  admin
    └── platform  Platform ◀
          └── taskflow  TaskFlow ◀
                envs  production, staging

---

3. Write orb.yaml

Create orb.yaml at the root of your app repo. Group definitions to match your settings UI:

plugin: taskflow

definitions:

  # ── Appearance (user scope — each user sets their own) ───────────────────────
  theme:
    type: enum
    values: [light, dark, system]
    scope: user
    default: system
    overridable: true
    label: Theme
    component: select

  accent_color:
    type: string
    scope: user
    default: "#6366f1"
    overridable: true
    label: Accent Color
    component: color

  language:
    type: enum
    values: [en, tr, de, fr, es]
    scope: user
    default: en
    overridable: true
    label: Language
    component: select

  # ── Notifications (user scope) ────────────────────────────────────────────────
  email_notifications:
    type: boolean
    scope: user
    default: true
    overridable: true
    label: Email Notifications
    component: toggle

  digest_frequency:
    type: enum
    values: [realtime, daily, weekly, never]
    scope: user
    default: daily
    overridable: true
    label: Digest Frequency
    component: select

  # ── Team / Workspace ──────────────────────────────────────────────────────────
  max_seats:
    type: number
    scope: workspace
    default: 5
    label: Max Team Seats

  allowed_domains:
    type: json
    scope: workspace
    default: []
    label: Allowed Email Domains

  # ── App Behavior (project scope) ──────────────────────────────────────────────
  default_view:
    type: enum
    values: [list, board, calendar, timeline]
    scope: project
    default: list
    overridable: true
    label: Default View
    component: select

  features:
    type: json
    scope: project
    default: { "ai_assist": false, "recurring_tasks": true, "time_tracking": false }
    label: Feature Flags

  # ── Infrastructure (environment scope) ───────────────────────────────────────
  app_url:
    type: string
    scope: environment
    required: true
    label: App URL

  cdn_url:
    type: string
    scope: environment
    default: "https://cdn.taskflow.app"
    label: CDN URL

  # ── Secrets (E2E encrypted, environment scope) ────────────────────────────────
  database_url:
    type: secret
    scope: environment
    required: true
    label: Database URL

  smtp_password:
    type: secret
    scope: environment
    required: true
    label: SMTP Password

  stripe_secret:
    type: secret
    scope: environment
    required: true
    label: Stripe Secret Key

---

4. Sync schema

With context set, no arguments needed:

npx orbseal sync

  plugin     taskflow
  created    13
  updated    0
  unchanged  0
  errors     0

Inspect:

npx orbseal schema list

  PLUGIN    KEY                   TYPE     SCOPE        REQ  SEC  VER
  ────────  ────────────────────  ───────  ───────────  ───  ───  ───
  taskflow  accent_color          string   user         no   no   1
  taskflow  allowed_domains       json     workspace    no   no   1
  taskflow  app_url               string   environment  yes  no   1
  taskflow  cdn_url               string   environment  no   no   1
  taskflow  database_url          secret   environment  yes  yes  1
  taskflow  default_view          enum     project      no   no   1
  taskflow  digest_frequency      enum     user         no   no   1
  taskflow  email_notifications   boolean  user         no   no   1
  taskflow  features              json     project      no   no   1
  taskflow  language              enum     user         no   no   1
  taskflow  max_seats             number   workspace    no   no   1
  taskflow  smtp_password         secret   environment  yes  yes  1
  taskflow  stripe_secret         secret   environment  yes  yes  1
  taskflow  theme                 enum     user         no   no   1

---

5. Set values per scope

All values commands use the active context — no need to repeat workspace/project.

Workspace defaults (apply to all projects in the org):

npx orbseal values set taskflow:max_seats 10 \
  --scope workspace --ref default

Project defaults (app-wide behavior):

npx orbseal values set taskflow:default_view board \
  --scope project --ref taskflow

npx orbseal values set taskflow:features \
  '{"ai_assist":true,"recurring_tasks":true,"time_tracking":false}' \
  --scope project --ref taskflow

Environment-specific (prod vs staging):

# production
npx orbseal values set taskflow:app_url https://app.taskflow.io \
  --scope environment --ref production

npx orbseal values set taskflow:cdn_url https://cdn.taskflow.io \
  --scope environment --ref production

# staging
npx orbseal values set taskflow:app_url https://staging.taskflow.io \
  --scope environment --ref staging

User override (a specific user prefers dark mode):

npx orbseal values set taskflow:theme dark \
  --scope user --ref user-id-abc123

Check the full value table:

npx orbseal values list

  PLUGIN    KEY                  SCOPE        SCOPE REF  VALUE         VER
  ────────  ───────────────────  ───────────  ─────────  ────────────  ───
  taskflow  max_seats            workspace    471b38a4…  10            1
  taskflow  default_view         project      d8453eeb…  "board"       1
  taskflow  features             project      d8453eeb…  {"ai_assis…   1
  taskflow  app_url              environment  d085878e…  "https://ap…  1
  taskflow  cdn_url              environment  d085878e…  "https://cd…  1
  taskflow  app_url              environment  f1dc9e97…  "https://st…  1
  taskflow  theme                user         user-id-…  "dark"        1

---

6. Generate keypair & seal secrets

npx orbseal keygen

  Recovery phrase — write this down and store safely:

  witch collapse practice feed shame open despair creek road again ice least

  public key   orbpk-6VqoWhXczDR1ydCHVFxhNhv8uQaWLicCHRiXQz5fXRet
  private key  orbsk-F1NdfoJULGa8qdaWr6xAbWeYz7bc5uu6EFwZ3AznGHua

Save the public key to context so you don't repeat it on every seal command:

npx orbseal use --public-key "orbpk-6VqoWhXczDR1ydCHVFxhNhv8uQaWLicCHRiXQz5fXRet"

✓ Public key saved to context.
  orbpk-6VqoWhXczDR1ydCHVF…

Create an app key for the production environment:

npx orbseal keys create "prod-worker" \
  --public-key "orbpk-6VqoWhXczDR1ydCHVFxhNhv8uQaWLicCHRiXQz5fXRet" \
  --env production

  App key created — save the token, it won't be shown again:

  orb_live_bca804b866e3c2968c13842a85aed0f2

Seal secrets — public key comes from context, no need to repeat it:

# Each secret is sealed client-side — orbseal never sees plaintext
npx orbseal seal taskflow:database_url --scope environment --ref production
# Secret value: [hidden input]

npx orbseal seal taskflow:smtp_password --scope environment --ref production
# Secret value: [hidden input]

npx orbseal seal taskflow:stripe_secret --scope environment --ref production
# Secret value: [hidden input]

---

7. Cut a release

npx orbseal release platform taskflow production

✓ Release v1  etag: 480a01d1eddb10ea

  project      taskflow
  environment  production
  version      1
  config keys  7
  secret keys  3

  Config snapshot:
    taskflow:allowed_domains          []
    taskflow:app_url                  "https://app.taskflow.io"
    taskflow:cdn_url                  "https://cdn.taskflow.io"
    taskflow:default_view             "board"
    taskflow:features                 {"ai_assist":true,"recurring_tasks":true,...}
    taskflow:max_seats                10
    taskflow:theme                    "system"

User preferences (theme, language, etc.) are not in the snapshot — they're merged live at resolve time.

---

8. Resolve at runtime

Switch to the app key and resolve:

npx orbseal login orb_live_bca804b866e3c2968c13842a85aed0f2
npx orbseal resolve

  etag: 419b5538602c197b  resolved: 2026-06-04 14:37:54

  Config
    taskflow:allowed_domains          []
    taskflow:app_url                  "https://app.taskflow.io"
    taskflow:cdn_url                  "https://cdn.taskflow.io"
    taskflow:default_view             "board"
    taskflow:features                 {"ai_assist":true,...}
    taskflow:language                 "en"
    taskflow:max_seats                10
    taskflow:theme                    "system"

  Secrets (ciphertext)
    taskflow:database_url             dPHsZMYpZT/3MlS2W2Dr…
    taskflow:smtp_password            MVqTx93vEm0Cid66PTSo…
    taskflow:stripe_secret            kR2xPQn8YwLmNp4JhTd7…

With a specific user's overrides (they set dark mode):

npx orbseal resolve --user=user-id-abc123

  Config
    ...
    taskflow:theme                    "dark"   ← user override wins
    ...

In your app (Node.js):

import _sodium from 'libsodium-wrappers';

const { config, secrets } = await fetch(
  'https://api.orbseal.com/v1/config/resolve?user=' + currentUserId,
  { headers: { Authorization: `Bearer ${process.env.ORBSEAL_TOKEN}` } }
).then(r => r.json());

// Non-secret config is ready to use
console.log(config['taskflow:theme']);          // "dark" (user override)
console.log(config['taskflow:default_view']);   // "board"
console.log(config['taskflow:features']);       // { ai_assist: true, ... }

// Decrypt secrets with the app's private key
await _sodium.ready;
const s  = _sodium;
const pk = s.from_base64(process.env.ORBSEAL_PUBLIC_KEY,  s.base64_variants.ORIGINAL);
const sk = s.from_base64(process.env.ORBSEAL_PRIVATE_KEY, s.base64_variants.ORIGINAL);

const dbUrl = s.to_string(
  s.crypto_box_seal_open(
    s.from_base64(secrets['taskflow:database_url'], s.base64_variants.ORIGINAL),
    pk, sk
  )
);

---

9. Update a setting — re-release

Changed your mind on feature flags? Update and re-release:

npx orbseal values set taskflow:features \
  '{"ai_assist":true,"recurring_tasks":true,"time_tracking":true}' \
  --scope project --ref taskflow

npx orbseal release platform taskflow production

✓ Release v2  etag: b6e633109fc23a62

Old snapshots are unchanged forever:

npx orbseal releases get platform taskflow production 1      # → time_tracking: false
npx orbseal releases get platform taskflow production 2      # → time_tracking: true
npx orbseal releases get platform taskflow production latest # → v2

---

The settings UI mapping

Every settings panel in your UI maps to an orbseal scope:

Settings Panel         orb.yaml scope    Who sets it
─────────────────────  ────────────────  ──────────────────────────
Appearance             user              User (overridable: true)
Notifications          user              User (overridable: true)
Team / Billing         workspace         Org admin
App Behavior           project           Developer / app admin
Infrastructure         environment       DevOps / deployment pipeline
Secrets                environment       Sealed by developer, read by app

The component field in each definition is a UI hint — your settings UI renderer can use it to pick the right input type (select, toggle, color, text, secret).

---

CLI quick reference

Command	Aliases	Description
orbseal ls		Tree view of orgs, workspaces, projects
orbseal use <org>[/<ws>[/<proj>]]		Set active context
orbseal use --public-key <key>		Save public key to context
orbseal use --clear		Clear context (including public key)
orbseal workspaces	orbseal ws	List workspaces
orbseal projects	orbseal proj	List projects (uses context)
orbseal envs	orbseal env	List environments (uses context)
orbseal sync		Sync orb.yaml (uses context)
orbseal schema list		List definitions (uses context)
orbseal values list		List set values (uses context)
orbseal whoami	orbseal wh	Show current token and API base

Commands that accept <workspace> and <project> arguments will fall back to the saved context when those arguments are omitted.

---

Recovering your keypair

If you lose the private key file, recover from your 12-word phrase:

orbseal recover "witch collapse practice feed shame open despair creek road again ice least"

  public key   orbpk-6VqoWhXczDR1ydCHVFxhNhv8uQaWLicCHRiXQz5fXRet
  private key  orbsk-F1NdfoJULGa8qdaWr6xAbWeYz7bc5uu6EFwZ3AznGHua

---

Status at a glance

orbseal status

  token  orb_admin_e8a79311…
  api    https://api.orbseal.com
  mode   admin

  ● acme  Acme  admin
    └── platform  Platform
          └── taskflow  TaskFlow
                envs        production, staging
                definitions 13
                app keys    1 active
                latest      v2  2026-06-04