cldz-cli 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# cldz
+
+A one-command launcher for [Claude Code](https://claude.com/claude-code). Pick an
+authentication method **once** — API key, OAuth token, a custom gateway, Amazon
+Bedrock, or Google Vertex AI — then just run `cldz`. It sets the right
+environment variables and hands off to `claude`, passing through any arguments.
+
+```bash
+npx cldz            # first run walks you through setup, then launches Claude Code
+```
+
+Or install it globally:
+
+```bash
+npm install -g cldz
+cldz
+```
+
+## Why
+
+Running Claude Code with different credentials normally means remembering and
+exporting the right environment variables every time:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...        # or
+export CLAUDE_CODE_OAUTH_TOKEN=...         # or
+export CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-east-1
+claude
+```
+
+`cldz` remembers your choices in `~/.cldz/config.json` and does that for you.
+
+## Auth methods
+
+| Method | Env vars it sets |
+| --- | --- |
+| **API key** | `ANTHROPIC_API_KEY` |
+| **OAuth token** (Pro / Max, from `claude setup-token`) | `CLAUDE_CODE_OAUTH_TOKEN` |
+| **Custom gateway / proxy** | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` |
+| **Amazon Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1`, `AWS_REGION`, `AWS_PROFILE` |
+| **Google Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1`, `ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION` |
+
+## Usage
+
+```bash
+cldz                         # launch with your default profile
+cldz -P work                 # launch with the "work" profile
+cldz -P work "fix the bug"   # extra args pass straight to claude
+cldz --dangerously-skip-permissions   # any claude flag passes through
+cldz -- --help               # force everything after -- through to claude
+```
+
+## Managing profiles
+
+```bash
+cldz --config                # interactive: add / edit / delete / rename / set-default
+cldz --list                  # list saved profiles
+cldz --set-default work       # set the default profile
+cldz --remove old             # delete a profile
+cldz --env work               # show the env vars a profile sets (secrets masked)
+cldz --doctor                 # check your setup
+```
+
+The `--config` menu lets you add multiple named profiles, edit them, delete them,
+rename them, and choose which one is the default.
+
+## Credential storage
+
+- When you opt in during setup, secrets are saved to `~/.cldz/config.json`
+  (written with `0600` permissions). On Windows this is `%USERPROFILE%\.cldz\config.json`.
+- If you'd rather **not** store a secret, decline the "save the secret?" prompt.
+  `cldz` will then read it from the environment each run.
+- **A matching environment variable always overrides the saved value at run time.**
+  So you can keep a profile for its type/region settings and inject the secret from
+  your shell or a secrets manager:
+
+  ```bash
+  ANTHROPIC_API_KEY=sk-ant-xxxx cldz -P work
+  ```
+
+## Session isolation
+
+By default, each profile launches `claude` with its **own** `CLAUDE_CONFIG_DIR`
+at `~/.cldz/sessions/<profile>/`. This matters:
+
+- **The profile's credential is guaranteed to be the one used.** If you're already
+  logged into Claude Code normally, that stored login would otherwise take
+  precedence over an injected token — isolation prevents that.
+- Each profile gets its own separate session, history, and settings. Your main
+  `~/.claude` login is never touched.
+
+The first launch of a fresh profile runs Claude Code's normal first-run setup
+(theme, trust prompt) inside that profile's dir. You can turn isolation off for a
+profile in `cldz --config` (it will then share your main `~/.claude`), or set
+`CLAUDE_CONFIG_DIR` yourself to override where it points.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `CLDZ_HOME` | Override the config directory (default `~/.cldz`) |
+| `CLDZ_CLAUDE_BIN` | Path to the `claude` binary (default `claude`) |
+| `CLDZ_PROFILE` | Default profile name to use |
+| `CLAUDE_CONFIG_DIR` | If set, cldz respects it instead of the per-profile isolated dir |
+
+## Requirements
+
+- Node.js >= 18
+- [Claude Code](https://claude.com/claude-code) installed (`npm i -g @anthropic-ai/claude-code`)
+
+## Support & Contributing
+
+Questions, bug reports, and contributions are welcome.
+
+- **Support / bugs:** email [iamthehimansh@gmail.com](mailto:iamthehimansh@gmail.com)
+- **Contributing:** PRs and issues are welcome. Please include steps to reproduce
+  for bugs, and keep the CLI dependency-free (it intentionally ships with zero
+  runtime dependencies). Run the CLI locally with `node bin/cldz.js` while developing.
+
+## License
+
+MIT © [iamthehimansh](mailto:iamthehimansh@gmail.com)
+
+MIT

package/bin/cldz.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/index.js');
+
+main(process.argv.slice(2)).catch((err) => {
+  if (err && err.code === 'CLDZ_ABORT') {
+    // User cancelled a prompt. Exit quietly.
+    process.exit(130);
+  }
+  console.error('cldz: ' + (err && err.message ? err.message : String(err)));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cldz-cli",
+  "version": "0.1.0",
+  "description": "One-command launcher for Claude Code — pick an auth method (API key / OAuth / gateway / Bedrock / Vertex) once and just run `cldz`.",
+  "type": "commonjs",
+  "bin": {
+    "cldz": "bin/cldz.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/cldz.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "cli",
+    "launcher",
+    "oauth",
+    "api-key",
+    "bedrock",
+    "vertex"
+  ],
+  "author": "iamthehimansh <iamthehimansh@gmail.com>",
+  "bugs": {
+    "email": "iamthehimansh@gmail.com"
+  },
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/auth.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// Definitions for every supported auth method and how each maps to the
+// environment variables Claude Code reads.
+//
+// Each field:
+//   key      - property name stored on the profile
+//   label    - prompt text
+//   env      - the environment variable Claude Code reads
+//   secret   - true => hidden input + treated as a secret
+//   optional - true => may be left blank
+//   default  - default value offered at the prompt
+const AUTH_TYPES = {
+  apiKey: {
+    label: 'API key',
+    hint: 'ANTHROPIC_API_KEY',
+    fields: [
+      { key: 'apiKey', label: 'Anthropic API key', env: 'ANTHROPIC_API_KEY', secret: true },
+    ],
+  },
+  oauth: {
+    label: 'OAuth token (Pro / Max)',
+    hint: 'from `claude setup-token`',
+    fields: [
+      { key: 'oauthToken', label: 'Claude Code OAuth token', env: 'CLAUDE_CODE_OAUTH_TOKEN', secret: true },
+    ],
+  },
+  gateway: {
+    label: 'Custom gateway / proxy',
+    hint: 'ANTHROPIC_BASE_URL',
+    fields: [
+      { key: 'baseUrl', label: 'Base URL (e.g. https://gateway.example.com)', env: 'ANTHROPIC_BASE_URL', secret: false },
+      { key: 'authToken', label: 'Auth token (blank if the gateway needs none)', env: 'ANTHROPIC_AUTH_TOKEN', secret: true, optional: true },
+    ],
+  },
+  bedrock: {
+    label: 'Amazon Bedrock',
+    hint: 'CLAUDE_CODE_USE_BEDROCK',
+    staticEnv: { CLAUDE_CODE_USE_BEDROCK: '1' },
+    note: 'Uses your standard AWS credentials (env, ~/.aws, or SSO).',
+    fields: [
+      { key: 'region', label: 'AWS region', env: 'AWS_REGION', secret: false, default: 'us-east-1' },
+      { key: 'awsProfile', label: 'AWS profile (blank = default credentials)', env: 'AWS_PROFILE', secret: false, optional: true },
+    ],
+  },
+  vertex: {
+    label: 'Google Vertex AI',
+    hint: 'CLAUDE_CODE_USE_VERTEX',
+    staticEnv: { CLAUDE_CODE_USE_VERTEX: '1' },
+    note: 'Uses Google Application Default Credentials (gcloud auth).',
+    fields: [
+      { key: 'project', label: 'GCP project ID', env: 'ANTHROPIC_VERTEX_PROJECT_ID', secret: false },
+      { key: 'region', label: 'Cloud ML region', env: 'CLOUD_ML_REGION', secret: false, default: 'us-east5' },
+    ],
+  },
+};
+
+const TYPE_ORDER = ['apiKey', 'oauth', 'gateway', 'bedrock', 'vertex'];
+
+function typeDef(type) {
+  const def = AUTH_TYPES[type];
+  if (!def) throw new Error(`unknown auth type: ${type}`);
+  return def;
+}
+
+function isSecretField(field) {
+  return Boolean(field.secret);
+}
+
+// Build the env var map to hand to `claude` from a fully-resolved profile
+// (i.e. one whose field values are already populated).
+function buildEnv(profile) {
+  const def = typeDef(profile.type);
+  const env = {};
+  if (def.staticEnv) Object.assign(env, def.staticEnv);
+  for (const field of def.fields) {
+    const value = profile[field.key];
+    if (value !== undefined && value !== null && value !== '') {
+      env[field.env] = String(value);
+    }
+  }
+  return env;
+}
+
+module.exports = { AUTH_TYPES, TYPE_ORDER, typeDef, buildEnv, isSecretField };

package/src/config.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs');
+const { configDir, configPath } = require('./paths.js');
+
+const CONFIG_VERSION = 1;
+
+function emptyConfig() {
+  return { version: CONFIG_VERSION, defaultProfile: null, profiles: {} };
+}
+
+function load() {
+  const file = configPath();
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyConfig();
+    throw err;
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`config file at ${file} is not valid JSON (${err.message}). Fix or delete it.`);
+  }
+  if (!data || typeof data !== 'object') return emptyConfig();
+  if (!data.profiles || typeof data.profiles !== 'object') data.profiles = {};
+  if (typeof data.version !== 'number') data.version = CONFIG_VERSION;
+  if (!('defaultProfile' in data)) data.defaultProfile = null;
+  return data;
+}
+
+function save(data) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = configPath();
+  // Write with restrictive perms (0600) since it may hold plaintext secrets.
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(file, 0o600);
+    } catch {
+      /* best effort */
+    }
+  }
+  return file;
+}
+
+function profileNames(data) {
+  return Object.keys(data.profiles);
+}
+
+function getProfile(data, name) {
+  return data.profiles[name] || null;
+}
+
+function setDefault(data, name) {
+  data.defaultProfile = name;
+}
+
+function removeProfile(data, name) {
+  delete data.profiles[name];
+  if (data.defaultProfile === name) {
+    const remaining = profileNames(data);
+    data.defaultProfile = remaining.length ? remaining[0] : null;
+  }
+}
+
+module.exports = {
+  CONFIG_VERSION,
+  emptyConfig,
+  load,
+  save,
+  profileNames,
+  getProfile,
+  setDefault,
+  removeProfile,
+  configPath,
+};

package/src/index.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+const config = require('./config.js');
+const manager = require('./manager.js');
+const { run } = require('./run.js');
+const tty = require('./tty.js');
+const { paint, colors: c } = tty;
+
+const pkg = require('../package.json');
+
+function printVersion() {
+  process.stdout.write(`cldz ${pkg.version}\n`);
+}
+
+function printHelp() {
+  const b = (s) => paint(c.bold, s);
+  process.stdout.write(`
+${b('cldz')} — a one-command launcher for Claude Code.
+
+Pick an auth method once (API key / OAuth / gateway / Bedrock / Vertex),
+then just run ${b('cldz')}. Any extra arguments are passed straight to ${b('claude')}.
+
+${b('USAGE')}
+  cldz [claude args...]           Launch Claude Code with your default profile
+  cldz -P <name> [claude args]    Launch using a specific profile
+  cldz -- <claude args>           Force everything through to claude (e.g. -- --help)
+
+${b('MANAGEMENT')}
+  cldz --config                   Interactive: add / edit / delete / set-default
+  cldz --list                     List saved profiles
+  cldz --set-default <name>       Set the default profile
+  cldz --remove <name>            Delete a profile
+  cldz --env [name]               Print the env vars a profile sets (secrets masked)
+  cldz --doctor                   Check your setup
+  cldz --help                     Show this help
+  cldz --version                  Show version
+
+${b('ISOLATION')}
+  By default each profile runs claude with its own CLAUDE_CONFIG_DIR
+  (~/.cldz/sessions/<profile>/), so the profile's credential is the one used and
+  your main ~/.claude login is untouched. Opt out per profile via ${b('cldz --config')}.
+
+${b('ENVIRONMENT')}
+  A matching env var always overrides the saved value at run time, e.g.
+  ${paint(c.dim, 'ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_BASE_URL,')}
+  ${paint(c.dim, 'ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX')}
+
+  CLDZ_HOME         Override config dir (default: ~/.cldz)
+  CLDZ_CLAUDE_BIN   Path to the claude binary (default: claude)
+  CLDZ_PROFILE      Default profile name to use
+
+Config is stored at ${paint(c.dim, config.configPath())}
+`);
+}
+
+function doctor() {
+  const ok = (s) => paint(c.green, '✓ ') + s;
+  const warn = (s) => paint(c.yellow, '! ') + s;
+
+  process.stdout.write(paint(c.bold, 'cldz doctor\n\n'));
+  process.stdout.write(ok(`node ${process.version}`) + '\n');
+
+  const bin = process.env.CLDZ_CLAUDE_BIN || 'claude';
+  try {
+    const out = execFileSync(bin, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    process.stdout.write(ok(`claude found: ${out.trim()}`) + '\n');
+  } catch {
+    process.stdout.write(
+      warn(`could not run "${bin} --version". Install it: npm i -g @anthropic-ai/claude-code`) + '\n'
+    );
+  }
+
+  const data = config.load();
+  const names = config.profileNames(data);
+  if (!names.length) {
+    process.stdout.write(warn('no profiles configured yet — run: cldz --config') + '\n');
+  } else {
+    process.stdout.write(ok(`${names.length} profile(s): ${names.join(', ')}`) + '\n');
+    process.stdout.write(ok(`default profile: ${data.defaultProfile || '(none)'}`) + '\n');
+  }
+  process.stdout.write(paint(c.dim, `config: ${config.configPath()}\n`));
+}
+
+// Parse argv into { command, profile, claudeArgs, rest }.
+function parse(argv) {
+  // Explicit force-passthrough: `cldz -- <claude args>`
+  if (argv[0] === '--') {
+    return { command: 'run', claudeArgs: argv.slice(1) };
+  }
+
+  const first = argv[0];
+
+  // Strip a `--profile` / `-P` selector wherever it appears before `--`.
+  let profile = process.env.CLDZ_PROFILE || undefined;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      // Everything after is passthrough; keep the marker so we can strip it later.
+      rest.push(...argv.slice(i));
+      break;
+    }
+    if (a === '--profile' || a === '-P') {
+      profile = argv[++i];
+      continue;
+    }
+    if (a.startsWith('--profile=')) {
+      profile = a.slice('--profile='.length);
+      continue;
+    }
+    rest.push(a);
+  }
+
+  // Recognize cldz management flags only when they lead the command.
+  switch (first) {
+    case '--config':
+      return { command: 'config' };
+    case '--list':
+    case '--profiles':
+      return { command: 'list' };
+    case '--env':
+      return { command: 'env', profile: argv[1] };
+    case '--doctor':
+      return { command: 'doctor' };
+    case '--set-default':
+      return { command: 'set-default', name: argv[1] };
+    case '--remove':
+    case '--delete':
+      return { command: 'remove', name: argv[1] };
+    case '--help':
+    case '-h':
+      return { command: 'help' };
+    case '--version':
+    case '-V':
+      return { command: 'version' };
+    default:
+      break;
+  }
+
+  // Run path: strip a leading `--` passthrough marker if present.
+  let claudeArgs = rest;
+  const dd = claudeArgs.indexOf('--');
+  if (dd !== -1) claudeArgs = [...claudeArgs.slice(0, dd), ...claudeArgs.slice(dd + 1)];
+  return { command: 'run', profile, claudeArgs };
+}
+
+async function main(argv) {
+  const parsed = parse(argv);
+
+  switch (parsed.command) {
+    case 'help':
+      return printHelp();
+    case 'version':
+      return printVersion();
+    case 'doctor':
+      return doctor();
+    case 'config':
+      return manager.manage();
+    case 'list':
+      return manager.listProfiles();
+    case 'env':
+      return manager.showEnv(parsed.profile);
+    case 'set-default': {
+      if (!parsed.name) throw new Error('usage: cldz --set-default <name>');
+      const data = config.load();
+      if (!data.profiles[parsed.name]) throw new Error(`profile "${parsed.name}" not found`);
+      config.setDefault(data, parsed.name);
+      config.save(data);
+      process.stdout.write(paint(c.green, `✓ Default profile is now "${parsed.name}".\n`));
+      return;
+    }
+    case 'remove': {
+      if (!parsed.name) throw new Error('usage: cldz --remove <name>');
+      const data = config.load();
+      if (!data.profiles[parsed.name]) throw new Error(`profile "${parsed.name}" not found`);
+      config.removeProfile(data, parsed.name);
+      config.save(data);
+      process.stdout.write(paint(c.green, `✓ Removed "${parsed.name}".\n`));
+      return;
+    }
+    case 'run':
+    default:
+      return run({ profile: parsed.profile, claudeArgs: parsed.claudeArgs || [] });
+  }
+}
+
+module.exports = { main, parse };

package/src/manager.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const config = require('./config.js');
+const { typeDef, buildEnv } = require('./auth.js');
+const { sessionDir } = require('./run.js');
+const wizard = require('./wizard.js');
+const tty = require('./tty.js');
+const { paint, colors: c } = tty;
+
+function maskSecrets(profile) {
+  const def = typeDef(profile.type);
+  const parts = [];
+  for (const field of def.fields) {
+    const val = profile[field.key];
+    if (val === undefined || val === '') continue;
+    parts.push(`${field.key}=${field.secret ? mask(val) : val}`);
+  }
+  return parts.join('  ');
+}
+
+function mask(val) {
+  const s = String(val);
+  if (s.length <= 8) return '••••';
+  return s.slice(0, 4) + '…' + s.slice(-4);
+}
+
+function printProfiles(data) {
+  const names = config.profileNames(data);
+  if (!names.length) {
+    process.stdout.write(paint(c.dim, '  (no profiles yet)\n'));
+    return;
+  }
+  for (const name of names) {
+    const p = data.profiles[name];
+    const isDefault = data.defaultProfile === name;
+    const star = isDefault ? paint(c.green, ' ★ default') : '';
+    const def = typeDef(p.type);
+    const iso = p.isolate === false ? '  ' + paint(c.yellow, '(shared login)') : '';
+    process.stdout.write(`  ${paint(c.bold, name)}  ${paint(c.dim, def.label)}${star}${iso}\n`);
+    const detail = maskSecrets(p);
+    if (detail) process.stdout.write(paint(c.dim, `      ${detail}\n`));
+  }
+}
+
+async function chooseProfile(data, message) {
+  const names = config.profileNames(data);
+  if (!names.length) return null;
+  return tty.select(
+    message,
+    names.map((n) => ({
+      name: n + (data.defaultProfile === n ? ' ★' : ''),
+      value: n,
+      hint: data.profiles[n].type,
+    }))
+  );
+}
+
+// Interactive config management loop (cldz --config).
+async function manage() {
+  const data = config.load();
+  process.stdout.write('\n' + paint(c.bold, 'cldz configuration') + '  ' + paint(c.dim, config.configPath()) + '\n\n');
+
+  for (;;) {
+    printProfiles(data);
+    process.stdout.write('\n');
+
+    const action = await tty.select('What would you like to do?', [
+      { name: 'Add a profile', value: 'add' },
+      { name: 'Edit a profile', value: 'edit' },
+      { name: 'Delete a profile', value: 'delete' },
+      { name: 'Set default profile', value: 'default' },
+      { name: 'Rename a profile', value: 'rename' },
+      { name: 'Save & exit', value: 'exit' },
+    ]).catch((e) => {
+      if (e.code === 'CLDZ_ABORT') return 'exit';
+      throw e;
+    });
+
+    process.stdout.write('\n');
+
+    if (action === 'exit') break;
+
+    try {
+      if (action === 'add') {
+        const name = await wizard.configureProfile(data, {});
+        config.save(data);
+        process.stdout.write(paint(c.green, `✓ Added "${name}".\n\n`));
+      } else if (action === 'edit') {
+        const name = await chooseProfile(data, 'Edit which profile?');
+        if (name) {
+          await wizard.configureProfile(data, { name });
+          config.save(data);
+          process.stdout.write(paint(c.green, `✓ Updated "${name}".\n\n`));
+        }
+      } else if (action === 'delete') {
+        const name = await chooseProfile(data, 'Delete which profile?');
+        if (name) {
+          const yes = await tty.confirm(`Delete "${name}"?`, { defaultValue: false });
+          if (yes) {
+            config.removeProfile(data, name);
+            config.save(data);
+            process.stdout.write(paint(c.green, `✓ Deleted "${name}".\n\n`));
+          }
+        }
+      } else if (action === 'default') {
+        const name = await chooseProfile(data, 'Set which profile as default?');
+        if (name) {
+          config.setDefault(data, name);
+          config.save(data);
+          process.stdout.write(paint(c.green, `✓ Default is now "${name}".\n\n`));
+        }
+      } else if (action === 'rename') {
+        const name = await chooseProfile(data, 'Rename which profile?');
+        if (name) {
+          const next = await tty.ask('New name', { defaultValue: name });
+          if (next && next !== name) {
+            if (data.profiles[next]) throw new Error(`"${next}" already exists`);
+            data.profiles[next] = data.profiles[name];
+            if (data.defaultProfile === name) data.defaultProfile = next;
+            delete data.profiles[name];
+            config.save(data);
+            process.stdout.write(paint(c.green, `✓ Renamed to "${next}".\n\n`));
+          }
+        }
+      }
+    } catch (err) {
+      if (err.code === 'CLDZ_ABORT') {
+        process.stdout.write(paint(c.dim, '(cancelled)\n\n'));
+      } else {
+        process.stdout.write(paint(c.red, `✗ ${err.message}\n\n`));
+      }
+    }
+  }
+
+  process.stdout.write(paint(c.dim, 'Saved. Run `cldz` to launch Claude Code.\n'));
+}
+
+// Non-interactive helpers used by subcommands.
+function listProfiles() {
+  const data = config.load();
+  process.stdout.write(paint(c.bold, 'Profiles') + '  ' + paint(c.dim, config.configPath()) + '\n');
+  printProfiles(data);
+}
+
+function showEnv(profileName) {
+  const data = config.load();
+  const name = profileName || data.defaultProfile || config.profileNames(data)[0];
+  if (!name || !data.profiles[name]) throw new Error('no profile configured. Run: cldz --config');
+  const p = data.profiles[name];
+  const env = buildEnv({ ...p });
+  if (p.isolate !== false) env.CLAUDE_CONFIG_DIR = sessionDir(name, p);
+  process.stdout.write(paint(c.dim, `# profile "${name}"\n`));
+  for (const [k, v] of Object.entries(env)) {
+    const secret = /TOKEN|KEY/.test(k);
+    process.stdout.write(`export ${k}=${secret ? mask(v) : v}\n`);
+  }
+}
+
+module.exports = { manage, listProfiles, showEnv, chooseProfile };

package/src/paths.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+
+// Resolve the cldz home directory in a cross-platform way.
+// Override with CLDZ_HOME for tests / custom locations.
+// - macOS / Linux:  ~/.cldz
+// - Windows:        C:\Users\<you>\.cldz   (os.homedir() -> %USERPROFILE%)
+function configDir() {
+  if (process.env.CLDZ_HOME && process.env.CLDZ_HOME.trim()) {
+    return process.env.CLDZ_HOME;
+  }
+  return path.join(os.homedir(), '.cldz');
+}
+
+function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+module.exports = { configDir, configPath };

package/src/run.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { typeDef, buildEnv } = require('./auth.js');
+const config = require('./config.js');
+const { configDir } = require('./paths.js');
+const wizard = require('./wizard.js');
+const tty = require('./tty.js');
+const { paint, colors: c } = tty;
+
+// Where an isolated profile keeps its own Claude Code config/credentials.
+function sessionDir(name, stored) {
+  return stored.configDir || path.join(configDir(), 'sessions', name);
+}
+
+// Unless the profile opts out (isolate: false) or the user already set
+// CLAUDE_CONFIG_DIR themselves, point claude at a per-profile config dir so the
+// profile's credential is the one actually used — a stored login in ~/.claude
+// otherwise takes precedence over an injected token. Returns the dir, or null.
+function applyIsolation(extraEnv, name, stored) {
+  if (stored.isolate === false) return null;
+  if (process.env.CLAUDE_CONFIG_DIR) return process.env.CLAUDE_CONFIG_DIR; // env override wins
+  const dir = sessionDir(name, stored);
+  fs.mkdirSync(dir, { recursive: true });
+  extraEnv.CLAUDE_CONFIG_DIR = dir;
+  return dir;
+}
+
+// Resolve a stored profile into concrete field values, letting a runtime
+// environment variable override the saved value. Prompts for anything that is
+// still missing (when interactive) and offers to save it.
+async function resolveProfile(data, name) {
+  const stored = data.profiles[name];
+  if (!stored) throw new Error(`profile "${name}" not found`);
+  const def = typeDef(stored.type);
+
+  const resolved = { type: stored.type };
+  const sources = {};
+  const missing = [];
+
+  for (const field of def.fields) {
+    const envVal = process.env[field.env];
+    if (envVal !== undefined && envVal !== '') {
+      resolved[field.key] = envVal;
+      sources[field.key] = 'env';
+    } else if (stored[field.key] !== undefined && stored[field.key] !== '') {
+      resolved[field.key] = stored[field.key];
+      sources[field.key] = 'config';
+    } else if (!field.optional) {
+      missing.push(field);
+    }
+  }
+
+  if (missing.length) {
+    if (!tty.isInteractive()) {
+      const names = missing.map((f) => '$' + f.env).join(', ');
+      throw new Error(
+        `profile "${name}" is missing required values (${names}). ` +
+          `Set the env var(s) or run: cldz --config`
+      );
+    }
+    process.stdout.write(
+      paint(c.yellow, `Profile "${name}" needs a few values:`) + '\n'
+    );
+    let touched = false;
+    for (const field of missing) {
+      const val = field.secret
+        ? await tty.askSecret('  ' + field.label)
+        : await tty.ask('  ' + field.label, { defaultValue: field.default || '' });
+      if (!val && !field.optional) throw new Error(`${field.label} is required`);
+      if (val) {
+        resolved[field.key] = val;
+        sources[field.key] = 'prompt';
+        touched = true;
+      }
+    }
+    if (touched) {
+      const store = await tty.confirm('Save these to the profile?', { defaultValue: true });
+      if (store) {
+        for (const field of missing) {
+          if (sources[field.key] === 'prompt') stored[field.key] = resolved[field.key];
+        }
+        config.save(data);
+      }
+    }
+  }
+
+  return { resolved, sources };
+}
+
+function pickDefaultProfileName(data) {
+  const names = config.profileNames(data);
+  if (data.defaultProfile && data.profiles[data.defaultProfile]) return data.defaultProfile;
+  if (names.length === 1) return names[0];
+  return null;
+}
+
+// Determine which profile to run, creating one if none exist.
+async function determineProfile(data, requested) {
+  if (requested) {
+    if (!data.profiles[requested]) {
+      throw new Error(`profile "${requested}" not found. Run: cldz --config`);
+    }
+    return requested;
+  }
+
+  const names = config.profileNames(data);
+  if (names.length === 0) {
+    process.stdout.write(paint(c.bold, 'Welcome to cldz — let’s set up authentication.\n\n'));
+    const name = await wizard.configureProfile(data, {});
+    config.save(data);
+    process.stdout.write(paint(c.green, `\n✓ Saved profile "${name}".\n\n`));
+    return name;
+  }
+
+  const chosen = pickDefaultProfileName(data);
+  if (chosen) return chosen;
+
+  // Multiple profiles, no default -> ask.
+  const choice = await tty.select(
+    'Which profile?',
+    names.map((n) => ({ name: n, value: n, hint: data.profiles[n].type }))
+  );
+  return choice;
+}
+
+function launchClaude(claudeArgs, extraEnv) {
+  // Release stdin (any open prompt interface) before claude inherits it.
+  tty.close();
+  const bin = process.env.CLDZ_CLAUDE_BIN || 'claude';
+  const env = { ...process.env, ...extraEnv };
+  const child = spawn(bin, claudeArgs, {
+    stdio: 'inherit',
+    env,
+    shell: process.platform === 'win32',
+  });
+  child.on('error', (err) => {
+    if (err.code === 'ENOENT') {
+      console.error(
+        `cldz: could not find "${bin}". Install Claude Code first:\n` +
+          '  npm install -g @anthropic-ai/claude-code'
+      );
+      process.exit(127);
+    }
+    console.error('cldz: failed to launch claude — ' + err.message);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code == null ? 0 : code);
+    }
+  });
+}
+
+// Entry point for the "run" path.
+async function run({ profile: requested, claudeArgs, quiet }) {
+  const data = config.load();
+  const name = await determineProfile(data, requested);
+  const { resolved, sources } = await resolveProfile(data, name);
+  const extraEnv = buildEnv(resolved);
+  const isolatedDir = applyIsolation(extraEnv, name, data.profiles[name]);
+
+  if (!quiet && process.stdout.isTTY) {
+    const def = typeDef(resolved.type);
+    const via = Object.values(sources).includes('env') ? paint(c.dim, ' (env override)') : '';
+    const iso = isolatedDir ? paint(c.dim, ' · isolated session') : '';
+    process.stderr.write(
+      paint(c.dim, `cldz › profile "${name}" · ${def.label}${via}${iso}\n`)
+    );
+  }
+
+  launchClaude(claudeArgs, extraEnv);
+}
+
+module.exports = { run, resolveProfile, determineProfile, launchClaude, sessionDir, applyIsolation };

package/src/tty.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const readline = require('node:readline');
+
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[90m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  bold: '\x1b[1m',
+};
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+function paint(color, str) {
+  return useColor ? color + str + c.reset : str;
+}
+
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+// One shared readline interface with a persistent line queue. `readline`'s
+// `question()` only captures a line while its transient listener is attached,
+// so piped input emitted between two awaited prompts is lost. Buffering every
+// line into a queue makes reads reliable for interactive TTYs and pipes alike.
+let rl = null;
+let muted = false;
+let ended = false;
+const queue = [];
+let waiter = null;
+
+function getRl() {
+  if (rl) return rl;
+  rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: Boolean(process.stdin.isTTY),
+  });
+  // Suppress echo while reading secrets.
+  rl._writeToOutput = (str) => {
+    if (!muted) rl.output.write(str);
+  };
+  rl.on('line', (line) => {
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w(line);
+    } else {
+      queue.push(line);
+    }
+  });
+  rl.on('close', () => {
+    ended = true;
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w(null);
+    }
+  });
+  rl.on('SIGINT', () => {
+    close();
+    process.stdout.write('\n');
+    process.exit(130);
+  });
+  return rl;
+}
+
+function nextLine() {
+  return new Promise((resolve) => {
+    if (queue.length) return resolve(queue.shift());
+    if (ended) return resolve(null);
+    waiter = resolve;
+  });
+}
+
+function close() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+async function ask(query, { defaultValue = '' } = {}) {
+  getRl();
+  const suffix = defaultValue ? paint(c.dim, ` (${defaultValue})`) : '';
+  process.stdout.write(`${query}${suffix}: `);
+  const line = await nextLine();
+  if (line === null) return defaultValue; // EOF
+  const val = line.trim();
+  return val === '' ? defaultValue : val;
+}
+
+// Hidden input for secrets (echo suppressed on a TTY; unavoidable on a pipe).
+async function askSecret(query) {
+  getRl();
+  process.stdout.write(`${query}: `);
+  muted = true;
+  const line = await nextLine();
+  muted = false;
+  process.stdout.write('\n');
+  return line === null ? '' : line.trim();
+}
+
+async function confirm(query, { defaultValue = true } = {}) {
+  const hint = defaultValue ? 'Y/n' : 'y/N';
+  const answer = (await ask(`${query} ${paint(c.dim, '[' + hint + ']')}`)).toLowerCase();
+  if (answer === '') return defaultValue;
+  return answer === 'y' || answer === 'yes';
+}
+
+// Numbered single-choice menu. Reliable across every terminal and on pipes.
+// choices: [{ name, value, hint }]
+async function select(message, choices) {
+  process.stdout.write(paint(c.bold, message) + '\n');
+  choices.forEach((choice, i) => {
+    const hint = choice.hint ? paint(c.dim, `  (${choice.hint})`) : '';
+    process.stdout.write(`  ${paint(c.cyan, String(i + 1))}) ${choice.name}${hint}\n`);
+  });
+  for (;;) {
+    const answer = await ask('Enter number', { defaultValue: '1' });
+    const n = parseInt(answer, 10);
+    if (!Number.isNaN(n) && n >= 1 && n <= choices.length) {
+      return choices[n - 1].value;
+    }
+    process.stdout.write(paint(c.red, `  Please enter 1-${choices.length}.\n`));
+  }
+}
+
+module.exports = { ask, askSecret, confirm, select, isInteractive, close, paint, colors: c };

package/src/wizard.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const { AUTH_TYPES, TYPE_ORDER, typeDef } = require('./auth.js');
+const tty = require('./tty.js');
+const { paint, colors: c } = tty;
+
+function suggestName(config, type) {
+  const base = type === 'apiKey' ? 'apikey' : type;
+  if (!config.profiles[base]) return base;
+  let i = 2;
+  while (config.profiles[`${base}${i}`]) i++;
+  return `${base}${i}`;
+}
+
+async function pickType(current) {
+  const choices = TYPE_ORDER.map((type) => ({
+    name: AUTH_TYPES[type].label + (type === current ? paint(c.dim, '  (current)') : ''),
+    value: type,
+    hint: AUTH_TYPES[type].hint,
+  }));
+  return tty.select('Which authentication method?', choices);
+}
+
+// Prompt for every field of a type. `existing` supplies defaults when editing.
+// Returns { values, hasSecret } where values are the entered field values.
+async function promptFields(type, existing = {}) {
+  const def = typeDef(type);
+  if (def.note) process.stdout.write(paint(c.dim, def.note) + '\n');
+
+  const values = {};
+  let hasSecret = false;
+
+  for (const field of def.fields) {
+    const envVal = process.env[field.env];
+    if (field.secret) {
+      hasSecret = true;
+      if (envVal) {
+        process.stdout.write(
+          paint(c.green, '✓') + ` ${field.label} detected in ${paint(c.dim, '$' + field.env)}\n`
+        );
+        const useEnv = await tty.confirm('  Use the value from the environment?', { defaultValue: true });
+        if (useEnv) {
+          // Leave unset so it is read from env at run time (not stored).
+          values[field.key] = undefined;
+          continue;
+        }
+      }
+      const hadStored = existing[field.key] ? paint(c.dim, ' (press Enter to keep saved value)') : '';
+      const entered = await tty.askSecret(`  ${field.label}${hadStored}`);
+      if (entered) values[field.key] = entered;
+      else if (existing[field.key]) values[field.key] = existing[field.key];
+      else if (!field.optional) throw new Error(`${field.label} is required`);
+    } else {
+      const def2 = existing[field.key] || envVal || field.default || '';
+      const entered = await tty.ask(`  ${field.label}`, { defaultValue: def2 });
+      if (entered) values[field.key] = entered;
+      else if (!field.optional) throw new Error(`${field.label} is required`);
+    }
+  }
+
+  return { values, hasSecret };
+}
+
+// Create or edit a profile interactively and persist it.
+// opts: { name?, type?, editing? }  -> returns the saved profile name.
+async function configureProfile(config, opts = {}) {
+  const editing = Boolean(opts.name && config.profiles[opts.name]);
+  const existing = editing ? config.profiles[opts.name] : {};
+
+  const type = opts.type || (await pickType(existing.type));
+  const { values, hasSecret } = await promptFields(type, existing);
+
+  const profile = { type };
+  for (const [k, v] of Object.entries(values)) {
+    if (v !== undefined) profile[k] = v;
+  }
+
+  // Decide whether to persist any secret in plaintext.
+  const def = typeDef(type);
+  const secretFields = def.fields.filter((f) => f.secret);
+  const enteredSecret = secretFields.some((f) => values[f.key] !== undefined);
+
+  if (enteredSecret) {
+    const store = await tty.confirm(
+      'Save the secret in ~/.cldz/config.json (plaintext)?',
+      { defaultValue: true }
+    );
+    if (!store) {
+      for (const f of secretFields) delete profile[f.key];
+      process.stdout.write(
+        paint(c.dim, `  Secret not saved — set $${secretFields.map((f) => f.env).join(' / $')} before running.`) + '\n'
+      );
+    }
+  }
+
+  // Isolation: keep this profile's Claude session (and its credential) separate
+  // from your main ~/.claude login. Recommended so the profile's credential is
+  // the one actually used.
+  const isolate = await tty.confirm(
+    'Keep this profile isolated from your main ~/.claude login (recommended)?',
+    { defaultValue: existing.isolate !== false }
+  );
+  if (isolate) delete profile.isolate;
+  else profile.isolate = false;
+
+  let name = opts.name;
+  if (!name) {
+    const suggested = suggestName(config, type);
+    name = await tty.ask('Profile name', { defaultValue: suggested });
+  }
+  if (!name) throw new Error('a profile name is required');
+
+  config.profiles[name] = profile;
+
+  // Default selection.
+  const onlyProfile = Object.keys(config.profiles).length === 1;
+  if (onlyProfile) {
+    config.defaultProfile = name;
+  } else if (config.defaultProfile !== name) {
+    const makeDefault = await tty.confirm(`Make "${name}" the default profile?`, {
+      defaultValue: !editing,
+    });
+    if (makeDefault) config.defaultProfile = name;
+  }
+
+  return name;
+}
+
+module.exports = { configureProfile, pickType, promptFields, suggestName };