@vendian/cli 0.0.1

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Vendian. All rights reserved.
+
+This software and its associated source code, package contents, documentation,
+and generated artifacts are proprietary to Vendian.
+
+No license is granted to copy, modify, merge, publish, distribute, sublicense,
+sell, reverse engineer, decompile, disassemble, or create derivative works from
+this software, except as expressly permitted in a separate written agreement
+with Vendian.
+
+Installation and use of this package are permitted only for accessing Vendian
+services and running Vendian-authorized workflows. Any other use is prohibited.
+
+This software is provided "as is" without warranty of any kind, express or
+implied, including but not limited to warranties of merchantability, fitness for
+a particular purpose, and noninfringement. Vendian is not liable for any claim,
+damages, or other liability arising from use of this software.

package/README.md

@@ -0,0 +1,51 @@
+# Vendian CLI
+
+Command-line tools for signing in to Vendian and running local agent workflows.
+
+```bash
+npm install -g @vendian/cli
+vendian login
+vendian cloud local serve --agents-dir ./agents
+```
+
+## Commands
+
+```bash
+vendian login
+vendian doctor
+vendian update
+vendian cloud local serve --agents-dir ./agents
+```
+
+`vendian login` opens a browser sign-in, prepares the local runtime, and stores
+the credentials needed by the CLI. `vendian setup` is kept as an alias for
+existing users.
+
+`vendian doctor` checks the local installation. `vendian update` refreshes the
+managed runtime without changing your agents.
+
+After login, regular `vendian cloud ...` commands are forwarded to the managed
+runtime installed by the CLI.
+
+## Local Data
+
+Vendian stores its managed runtime and CLI state under your user profile:
+
+- Windows: `%LOCALAPPDATA%\Vendian\cli`
+- macOS/Linux: `~/.vendian/cli`
+
+To use a different location:
+
+```bash
+VENDIAN_CLI_HOME=/path/to/vendian-cli vendian login
+```
+
+## Agent Dependencies
+
+Keep agent-specific packages in each agent's `requirements.txt`. The Vendian
+CLI manages the Vendian runtime separately so agent dependencies stay focused on
+the agent's own code.
+
+## License
+
+Proprietary. All rights reserved. See `LICENSE`.

package/bin/vendian.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/main.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  const message = error && typeof error.message === 'string' ? error.message : String(error);
+  console.error(`[vendian] ${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@vendian/cli",
+  "version": "0.0.1",
+  "description": "Public Vendian CLI bootstrapper and launcher",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "bin": {
+    "vendian": "bin/vendian.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  }
+}

package/src/auth.js

@@ -0,0 +1,239 @@
+import crypto from 'node:crypto';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { BACKEND_TARGETS } from './constants.js';
+
+const DEFAULT_OAUTH_REDIRECT_PORT = 8765;
+
+export function resolveApiUrl({ backend, apiUrl, env = process.env } = {}) {
+  if (apiUrl) {
+    return apiUrl.replace(/\/$/, '');
+  }
+  if (env.VENDIAN_API_URL) {
+    return env.VENDIAN_API_URL.replace(/\/$/, '');
+  }
+  const target = backend || 'prod';
+  const resolved = BACKEND_TARGETS[target];
+  if (!resolved) {
+    throw new Error(`Unknown Vendian backend '${target}'. Use local, dev, staging, prod, or --api-url.`);
+  }
+  return resolved;
+}
+
+export async function loginWithVendianOAuth({ backend, apiUrl, noBrowser = false, env = process.env } = {}) {
+  const resolvedApiUrl = resolveApiUrl({ backend, apiUrl, env });
+  const callback = await createCallbackServer(env);
+  try {
+    const config = await getOAuthConfig(resolvedApiUrl, callback.redirectUri);
+    const codeVerifier = crypto.randomBytes(48).toString('base64url');
+    const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+    const state = crypto.randomBytes(18).toString('base64url');
+    const authorizationUrl = authorizationUrlFor(config, { state, codeChallenge });
+
+    if (noBrowser) {
+      console.error(`Open this URL to authenticate the CLI: ${authorizationUrl}`);
+    } else {
+      openBrowser(authorizationUrl);
+    }
+
+    const callbackResult = await callback.wait();
+    if (callbackResult.state !== state) {
+      throw new Error('OAuth state mismatch');
+    }
+    const clerkToken = await exchangeCodeForClerkToken(config, callbackResult.code, codeVerifier, callback.redirectUri);
+    const exchange = await postJson(`${resolvedApiUrl}/api/v1/cli/auth/oauth/exchange`, {
+      clerkToken
+    });
+    return { apiUrl: resolvedApiUrl, ...exchange };
+  } finally {
+    await callback.close();
+  }
+}
+
+async function getOAuthConfig(apiUrl, redirectUri) {
+  const url = new URL(`${apiUrl}/api/v1/cli/auth/oauth/config`);
+  url.searchParams.set('redirectUri', redirectUri);
+  return getJson(url);
+}
+
+function authorizationUrlFor(config, { state, codeChallenge }) {
+  const url = new URL(String(config.authorizationUrl));
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', String(config.clientId));
+  url.searchParams.set('redirect_uri', String(config.redirectUri));
+  url.searchParams.set('scope', String(config.scopes || 'email profile'));
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  return url.toString();
+}
+
+async function exchangeCodeForClerkToken(config, code, codeVerifier, redirectUri) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: String(config.clientId),
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: codeVerifier
+  });
+  const payload = await postForm(String(config.tokenUrl), body);
+  const token = payload.access_token || payload.id_token;
+  if (!token) {
+    throw new Error('OAuth token exchange did not return a Clerk token');
+  }
+  return String(token);
+}
+
+async function getJson(url) {
+  const response = await fetch(url, { headers: { Accept: 'application/json' } });
+  return decodeResponse(response);
+}
+
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(body)
+  });
+  return decodeResponse(response);
+}
+
+async function postForm(url, body) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
+    body
+  });
+  return decodeResponse(response);
+}
+
+async function decodeResponse(response) {
+  const text = await response.text();
+  let payload = {};
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { error: text };
+    }
+  }
+  if (!response.ok) {
+    throw new Error(payload.message || payload.error || `HTTP ${response.status}`);
+  }
+  return payload;
+}
+
+async function createCallbackServer(env) {
+  const port = Number(env.VENDIAN_CLI_OAUTH_REDIRECT_PORT || DEFAULT_OAUTH_REDIRECT_PORT);
+  let server;
+  let settled = false;
+  let timeout;
+  const waitPromise = new Promise((resolve, reject) => {
+    timeout = setTimeout(() => {
+      settled = true;
+      reject(new Error('OAuth login timed out before callback completed'));
+    }, 300_000);
+    server = http.createServer((req, res) => {
+      const url = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      const error = url.searchParams.get('error');
+      const body = code
+        ? 'Vendian CLI authentication complete. You can close this window.'
+        : 'Vendian CLI authentication failed. Return to the terminal.';
+      res.writeHead(code ? 200 : 400, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body)
+      });
+      res.end(body);
+      clearTimeout(timeout);
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        reject(new Error(`OAuth login failed: ${error}`));
+        return;
+      }
+      if (!code) {
+        reject(new Error('OAuth callback did not include an authorization code'));
+        return;
+      }
+      resolve({ code, state });
+    });
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1');
+  });
+  await new Promise((resolve, reject) => {
+    server.once('listening', resolve);
+    server.once('error', reject);
+  });
+
+  return {
+    redirectUri: `http://127.0.0.1:${server.address().port}/callback`,
+    wait: () => waitPromise,
+    close: () => new Promise((resolve) => server.close(resolve))
+  };
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    spawnSync(...buildWindowsOpenCommand(url), { stdio: 'ignore', shell: false });
+    return;
+  }
+  if (platform === 'darwin') {
+    spawnSync('open', [url], { stdio: 'ignore', shell: false });
+    return;
+  }
+  spawnSync('xdg-open', [url], { stdio: 'ignore', shell: false });
+}
+
+export function buildWindowsOpenCommand(url) {
+  return ['rundll32.exe', ['url.dll,FileProtocolHandler', String(url)]];
+}
+
+export function cloudConfigPath(env = process.env, platform = process.platform) {
+  if (env.VENDIAN_CLOUD_CONFIG) {
+    return path.resolve(env.VENDIAN_CLOUD_CONFIG);
+  }
+  if (platform === 'win32') {
+    const root = env.APPDATA || path.join(process.env.USERPROFILE || '', 'AppData', 'Roaming');
+    return path.win32.join(root, 'Vendian', 'cloud-auth.json');
+  }
+  const root = env.XDG_CONFIG_HOME || path.join(process.env.HOME || '', '.config');
+  return path.posix.join(root, 'vendian', 'cloud-auth.json');
+}
+
+export function saveCloudToken(token, { env = process.env, platform = process.platform } = {}) {
+  const file = cloudConfigPath(env, platform);
+  let raw = { version: 2, profiles: {}, active_api_url: token.apiUrl };
+  try {
+    const existing = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (existing && typeof existing === 'object' && existing.profiles && typeof existing.profiles === 'object') {
+      raw.profiles = existing.profiles;
+    }
+  } catch {
+    // Missing or invalid config is replaced.
+  }
+  raw.active_api_url = token.apiUrl;
+  raw.profiles[token.apiUrl] = {
+    api_url: token.apiUrl,
+    access_token: token.accessToken,
+    user_id: token.userId,
+    email: token.email,
+    expires_at: token.expiresAt,
+    scopes: token.scopes,
+    tooling_eligible: token.toolingEligible
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(raw, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best effort on Windows filesystems.
+  }
+  return file;
+}

package/src/config.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_VERSION } from './constants.js';
+import { configPath } from './paths.js';
+
+export function loadConfig(env = process.env, platform = process.platform) {
+  const file = configPath(env, platform);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return {};
+    }
+    return {};
+  }
+}
+
+export function saveConfig(config, env = process.env, platform = process.platform) {
+  const file = configPath(env, platform);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const next = { version: CONFIG_VERSION, ...config };
+  fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best effort on Windows filesystems.
+  }
+  return file;
+}
+
+export function redact(value) {
+  if (!value || typeof value !== 'string') {
+    return value;
+  }
+  if (value.length <= 8) {
+    return '********';
+  }
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}

package/src/constants.js

@@ -0,0 +1,15 @@
+export const DEFAULT_GITLAB_HOST = 'gitlab.com';
+export const DEFAULT_SDK_PUBLIC_PROJECT_ID = '77150592';
+export const DEFAULT_SDK_RUNTIME_PROJECT_ID = '79410876';
+export const PUBLIC_PACKAGE = 'vendian-agents[full]';
+export const RUNTIME_PACKAGE = 'vendian-agents-runtime';
+export const CONFIG_VERSION = 1;
+
+export const BACKEND_TARGETS = {
+  local: 'http://localhost:3000',
+  localhost: 'http://localhost:3000',
+  dev: 'https://api.dev.vendian.ai',
+  staging: 'https://api.staging.vendian.ai',
+  prod: 'https://api.vendian.ai',
+  production: 'https://api.vendian.ai'
+};

package/src/doctor.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import { loadConfig, redact } from './config.js';
+import { registryConfig } from './install.js';
+import { managedVenvPath, venvPython, venvVendian } from './paths.js';
+import { findPython, hasUv, pythonVersion, verifyVendianImports } from './python.js';
+
+export function doctor({ env = process.env, platform = process.platform } = {}) {
+  const config = loadConfig(env, platform);
+  const venvPath = managedVenvPath(env, platform);
+  const pythonPath = venvPython(venvPath, platform);
+  const vendianPath = venvVendian(venvPath, platform);
+  const registry = registryConfig(config, env, platform);
+
+  console.log('Vendian doctor');
+  console.log(`Home: ${venvPath}`);
+  console.log(`System Python 3.11+: ${findPython(platform) ? 'yes' : 'no'}`);
+  console.log(`uv: ${hasUv() ? 'yes' : 'no, will use pip fallback'}`);
+  console.log(`Managed Python: ${fs.existsSync(pythonPath) ? pythonVersion(pythonPath) || 'present' : 'missing'}`);
+  console.log(`Vendian executable: ${fs.existsSync(vendianPath) ? vendianPath : 'missing'}`);
+  console.log(`Vendian imports: ${fs.existsSync(pythonPath) && verifyVendianImports(pythonPath) ? 'ok' : 'missing'}`);
+  console.log(`GitLab host: ${registry.gitlabHost}`);
+  console.log(`Package token: ${registry.token ? `${redact(registry.token)} (${registry.tokenSource})` : 'missing'}`);
+}

package/src/forward.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { loadConfig, saveConfig } from './config.js';
+import { installVendianPackages, registryConfig } from './install.js';
+import { managedVenvPath, venvPython, venvVendian } from './paths.js';
+import { spawnForward } from './process.js';
+
+const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export async function forwardToPythonVendian(args, { env = process.env, platform = process.platform } = {}) {
+  const venvPath = managedVenvPath(env, platform);
+  const vendianPath = venvVendian(venvPath, platform);
+  if (!fs.existsSync(vendianPath)) {
+    throw new Error('Vendian is not set up yet. Run `vendian login` first.');
+  }
+  maybeAutoUpdateManagedEnv({ env, platform, venvPath });
+  const code = await spawnForward(vendianPath, args, { env });
+  process.exitCode = code;
+}
+
+export function maybeAutoUpdateManagedEnv({ env = process.env, platform = process.platform, venvPath = managedVenvPath(env, platform) } = {}) {
+  if (env.VENDIAN_SKIP_AUTO_UPDATE === '1') {
+    return false;
+  }
+  const config = loadConfig(env, platform);
+  const lastUpdate = Date.parse(config.lastManagedUpdateAt || '');
+  if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < AUTO_UPDATE_INTERVAL_MS) {
+    return false;
+  }
+  const registry = registryConfig(config, env);
+  if (!registry.token) {
+    return false;
+  }
+  const pythonPath = venvPython(venvPath, platform);
+  if (!fs.existsSync(pythonPath)) {
+    return false;
+  }
+  try {
+    console.error('[vendian] Checking managed CLI/runtime updates...');
+    installVendianPackages({ pythonPath, venvPath, config, env });
+    saveConfig({ ...config, lastManagedUpdateAt: new Date().toISOString() }, env, platform);
+    return true;
+  } catch (error) {
+    const message = error && typeof error.message === 'string' ? error.message : String(error);
+    console.error(`[vendian] Update check failed; continuing with installed CLI. ${message}`);
+    return false;
+  }
+}

package/src/install.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  DEFAULT_GITLAB_HOST,
+  DEFAULT_SDK_PUBLIC_PROJECT_ID,
+  DEFAULT_SDK_RUNTIME_PROJECT_ID,
+  PUBLIC_PACKAGE,
+  RUNTIME_PACKAGE
+} from './constants.js';
+import { runInherit } from './process.js';
+import { hasUv } from './python.js';
+import { loadPackageTokenSecret } from './secret-store.js';
+
+export function registryConfig(config = {}, env = process.env, platform = process.platform) {
+  const gitlabHost = env.GITLAB_HOST || config.gitlabHost || DEFAULT_GITLAB_HOST;
+  const username = env.GITLAB_USERNAME || config.gitlabUsername || '__token__';
+  const sdkProjectId = env.SDK_PUBLIC_PROJECT_ID || config.sdkPublicProjectId || DEFAULT_SDK_PUBLIC_PROJECT_ID;
+  const runtimeProjectId = env.SDK_RUNTIME_PROJECT_ID || config.sdkRuntimeProjectId || DEFAULT_SDK_RUNTIME_PROJECT_ID;
+  const secretToken = loadPackageTokenSecret(config, platform);
+  const token = env.GITLAB_TOKEN || config.gitlabToken || secretToken || '';
+  const tokenSource = env.GITLAB_TOKEN ? 'env' : config.gitlabToken ? 'config' : secretToken ? 'secret-store' : 'missing';
+  const vendianAgentsVersion = env.VENDIAN_AGENTS_VERSION || config.vendianAgentsVersion || '';
+  const vendianRuntimeVersion = env.VENDIAN_AGENTS_RUNTIME_VERSION || config.vendianAgentsRuntimeVersion || '';
+
+  return {
+    gitlabHost,
+    username,
+    sdkProjectId,
+    runtimeProjectId,
+    token,
+    tokenSource,
+    vendianAgentsVersion,
+    vendianRuntimeVersion
+  };
+}
+
+export function buildIndexUrls(registry) {
+  if (!registry.token) {
+    return null;
+  }
+  const username = encodeURIComponent(registry.username || '__token__');
+  const token = encodeURIComponent(registry.token);
+  const sdkIndexUrl = `https://${username}:${token}@${registry.gitlabHost}/api/v4/projects/${registry.sdkProjectId}/packages/pypi/simple`;
+  const runtimeIndexUrl = `https://${username}:${token}@${registry.gitlabHost}/api/v4/projects/${registry.runtimeProjectId}/packages/pypi/simple`;
+  return { sdkIndexUrl, runtimeIndexUrl };
+}
+
+export function packageSpecs(registry) {
+  const publicSpec = registry.vendianAgentsVersion
+    ? `${PUBLIC_PACKAGE}==${registry.vendianAgentsVersion}`
+    : PUBLIC_PACKAGE;
+  const runtimeSpec = registry.vendianRuntimeVersion
+    ? `${RUNTIME_PACKAGE}==${registry.vendianRuntimeVersion}`
+    : RUNTIME_PACKAGE;
+  return [publicSpec, runtimeSpec];
+}
+
+export function installVendianPackages({ pythonPath, venvPath, config, env = process.env, platform = process.platform }) {
+  const registry = registryConfig(config, env, platform);
+  const indexes = buildIndexUrls(registry);
+  if (!indexes) {
+    throw new Error('A GitLab package token is required until backend-issued package tokens are available. Run `vendian setup` or set GITLAB_TOKEN.');
+  }
+
+  const specs = packageSpecs(registry);
+  const installArgs = [
+    'install',
+    '--upgrade',
+    ...specs,
+    '--index-url',
+    indexes.sdkIndexUrl,
+    '--extra-index-url',
+    indexes.runtimeIndexUrl,
+    '--extra-index-url',
+    'https://pypi.org/simple'
+  ];
+
+  let status;
+  if (hasUv()) {
+    status = runInherit('uv', ['pip', ...installArgs, '--python', pythonPath]);
+  } else {
+    status = runInherit(pythonPath, ['-m', 'pip', ...installArgs]);
+  }
+  if (status !== 0) {
+    throw new Error('Could not install Vendian SDK/runtime packages. Check token access and package versions.');
+  }
+
+  writeInstallMarker(venvPath, {
+    gitlabHost: registry.gitlabHost,
+    gitlabUsername: registry.username,
+    sdkProjectId: registry.sdkProjectId,
+    runtimeProjectId: registry.runtimeProjectId,
+    vendianAgentsVersion: registry.vendianAgentsVersion || 'latest',
+    vendianAgentsRuntimeVersion: registry.vendianRuntimeVersion || 'latest'
+  });
+}
+
+export function writeInstallMarker(venvPath, marker) {
+  fs.mkdirSync(venvPath, { recursive: true });
+  fs.writeFileSync(
+    path.join(venvPath, '.vendian-bootstrap.json'),
+    `${JSON.stringify({ version: 1, ...marker }, null, 2)}\n`,
+    'utf8'
+  );
+}

package/src/main.js

@@ -0,0 +1,80 @@
+import { doctor } from './doctor.js';
+import { forwardToPythonVendian } from './forward.js';
+import { setup } from './setup.js';
+
+function printHelp() {
+  console.log(`Vendian CLI bootstrapper
+
+Usage:
+  vendian login                 Sign in and install the private Vendian CLI/runtime
+  vendian setup                 Alias for vendian login
+  vendian doctor                Check local bootstrap health
+  vendian update                Update the managed Vendian CLI/runtime
+  vendian <command>             Forward to the managed Python Vendian CLI
+
+Examples:
+  vendian login
+  vendian login --backend prod
+  vendian cloud local serve --agents-dir ./agents
+
+Environment:
+  VENDIAN_CLI_HOME              Override managed CLI home
+  VENDIAN_API_URL               Override Vendian backend API URL
+  GITLAB_TOKEN                  Local-dev package registry token fallback
+  GITLAB_USERNAME               Local-dev package registry username fallback
+  GITLAB_HOST                   Defaults to gitlab.com
+  SDK_PUBLIC_PROJECT_ID         Defaults to Vendian SDK project
+  SDK_RUNTIME_PROJECT_ID        Defaults to Vendian runtime project
+`);
+}
+
+export async function main(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+  if (command === '--version' || command === 'version') {
+    console.log('0.1.0');
+    return;
+  }
+  if (isBootstrapCommand(command)) {
+    await setup(parseSetupOptions(rest));
+    return;
+  }
+  if (command === 'doctor') {
+    doctor();
+    return;
+  }
+  if (command === 'update') {
+    await setup({ nonInteractive: true });
+    return;
+  }
+  await forwardToPythonVendian(argv);
+}
+
+export function isBootstrapCommand(command) {
+  return command === 'login' || command === 'setup';
+}
+
+function parseSetupOptions(args) {
+  const options = {
+    nonInteractive: args.includes('--yes') || args.includes('--non-interactive'),
+    noBrowser: args.includes('--no-browser')
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--backend' || arg === '-b') {
+      options.backend = args[index + 1];
+      index += 1;
+    } else if (arg.startsWith('--backend=')) {
+      options.backend = arg.slice('--backend='.length);
+    } else if (arg === '--api-url') {
+      options.apiUrl = args[index + 1];
+      index += 1;
+    } else if (arg.startsWith('--api-url=')) {
+      options.apiUrl = arg.slice('--api-url='.length);
+    }
+  }
+  return options;
+}

package/src/paths.js

@@ -0,0 +1,43 @@
+import os from 'node:os';
+import path from 'node:path';
+
+function pathApi(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+export function vendianHome(env = process.env, platform = process.platform) {
+  if (env.VENDIAN_CLI_HOME) {
+    return pathApi(platform).resolve(env.VENDIAN_CLI_HOME);
+  }
+  if (platform === 'win32') {
+    const root = env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.win32.join(root, 'Vendian', 'cli');
+  }
+  return path.posix.join(os.homedir(), '.vendian', 'cli');
+}
+
+export function configPath(env = process.env, platform = process.platform) {
+  if (env.VENDIAN_CLI_CONFIG) {
+    return pathApi(platform).resolve(env.VENDIAN_CLI_CONFIG);
+  }
+  return pathApi(platform).join(vendianHome(env, platform), 'config.json');
+}
+
+export function managedVenvPath(env = process.env, platform = process.platform) {
+  if (env.VENDIAN_CLI_VENV) {
+    return pathApi(platform).resolve(env.VENDIAN_CLI_VENV);
+  }
+  return pathApi(platform).join(vendianHome(env, platform), '.venv');
+}
+
+export function venvPython(venvPath, platform = process.platform) {
+  return platform === 'win32'
+    ? path.win32.join(venvPath, 'Scripts', 'python.exe')
+    : path.posix.join(venvPath, 'bin', 'python');
+}
+
+export function venvVendian(venvPath, platform = process.platform) {
+  return platform === 'win32'
+    ? path.win32.join(venvPath, 'Scripts', 'vendian.exe')
+    : path.posix.join(venvPath, 'bin', 'vendian');
+}

package/src/process.js

@@ -0,0 +1,50 @@
+import { spawn, spawnSync } from 'node:child_process';
+
+export function commandExists(command) {
+  const result = spawnSync(command, ['--version'], { stdio: 'ignore', shell: false });
+  return result.status === 0;
+}
+
+export function runCapture(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    shell: false,
+    ...options
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status ?? 1,
+    stdout: result.stdout || '',
+    stderr: result.stderr || ''
+  };
+}
+
+export function runInherit(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: 'inherit',
+    shell: false,
+    ...options
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  return result.status ?? 1;
+}
+
+export function spawnForward(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      shell: false,
+      ...options
+    });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        reject(new Error(`command terminated by ${signal}`));
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/prompt.js

@@ -0,0 +1,38 @@
+import readline from 'node:readline';
+
+export function prompt(question, { defaultValue, secret = false } = {}) {
+  const suffix = defaultValue ? ` [${defaultValue}]` : '';
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true
+  });
+
+  if (!secret) {
+    return new Promise((resolve) => {
+      rl.question(`${question}${suffix}: `, (answer) => {
+        rl.close();
+        resolve(answer.trim() || defaultValue || '');
+      });
+    });
+  }
+
+  const originalWrite = rl._writeToOutput;
+  rl._writeToOutput = function writeHidden(stringToWrite) {
+    if (rl.stdoutMuted) {
+      rl.output.write(stringToWrite.replace(/[^\r\n]/g, '*'));
+    } else {
+      originalWrite.call(rl, stringToWrite);
+    }
+  };
+
+  return new Promise((resolve) => {
+    rl.stdoutMuted = true;
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.stdoutMuted = false;
+      rl.output.write('\n');
+      rl.close();
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}

package/src/python.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import { commandExists, runCapture, runInherit } from './process.js';
+import { venvPython } from './paths.js';
+
+export function findPython(platform = process.platform) {
+  const candidates = platform === 'win32'
+    ? [
+        { command: 'py', args: ['-3.11'] },
+        { command: 'python', args: [] },
+        { command: 'python3', args: [] }
+      ]
+    : [
+        { command: 'python3.12', args: [] },
+        { command: 'python3.11', args: [] },
+        { command: 'python3', args: [] },
+        { command: 'python', args: [] }
+      ];
+
+  for (const candidate of candidates) {
+    const version = runCapture(candidate.command, [
+      ...candidate.args,
+      '-c',
+      'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+    ]);
+    if (!version.ok) {
+      continue;
+    }
+    const match = version.stdout.trim().match(/^(\d+)\.(\d+)\./);
+    if (!match) {
+      continue;
+    }
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (major > 3 || (major === 3 && minor >= 11)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function ensureVenv(venvPath, pythonCandidate, platform = process.platform) {
+  const pythonPath = venvPython(venvPath, platform);
+  if (fs.existsSync(pythonPath)) {
+    return pythonPath;
+  }
+  fs.mkdirSync(venvPath, { recursive: true });
+  const status = runInherit(pythonCandidate.command, [
+    ...pythonCandidate.args,
+    '-m',
+    'venv',
+    venvPath
+  ]);
+  if (status !== 0) {
+    throw new Error('Could not create the managed Vendian Python environment.');
+  }
+  return pythonPath;
+}
+
+export function hasUv() {
+  return commandExists('uv');
+}
+
+export function pythonVersion(pythonPath) {
+  const result = runCapture(pythonPath, [
+    '-c',
+    'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")'
+  ]);
+  return result.ok ? result.stdout.trim() : null;
+}
+
+export function verifyVendianImports(pythonPath) {
+  const result = runCapture(pythonPath, [
+    '-c',
+    'import vendian_agents, vendian_agents_runtime; print("ok")'
+  ]);
+  return result.ok;
+}

package/src/secret-store.js

@@ -0,0 +1,94 @@
+import { spawnSync } from 'node:child_process';
+
+const SERVICE = 'Vendian CLI';
+const PACKAGE_TOKEN_ACCOUNT = 'gitlab-package-token';
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+    shell: false,
+    ...options
+  });
+}
+
+export function packageTokenSecretName() {
+  return PACKAGE_TOKEN_ACCOUNT;
+}
+
+export function savePackageTokenSecret(token, config = {}, platform = process.platform) {
+  if (!token) {
+    return { ok: false };
+  }
+  if (platform === 'darwin') {
+    const result = run('security', [
+      'add-generic-password',
+      '-a',
+      PACKAGE_TOKEN_ACCOUNT,
+      '-s',
+      SERVICE,
+      '-w',
+      token,
+      '-U'
+    ]);
+    return { ok: result.status === 0, provider: 'macos-keychain' };
+  }
+  if (platform === 'win32') {
+    const encrypted = run(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        '$secure = ConvertTo-SecureString -String $env:VENDIAN_SECRET_VALUE -AsPlainText -Force; $secure | ConvertFrom-SecureString'
+      ],
+      { env: { ...process.env, VENDIAN_SECRET_VALUE: token } }
+    );
+    if (encrypted.status !== 0 || !encrypted.stdout.trim()) {
+      return { ok: false, provider: 'windows-dpapi' };
+    }
+    const nextConfig = {
+      ...config,
+      secretStore: {
+        ...(config.secretStore || {}),
+        [PACKAGE_TOKEN_ACCOUNT]: {
+          provider: 'windows-dpapi',
+          value: encrypted.stdout.trim()
+        }
+      }
+    };
+    return { ok: true, provider: 'windows-dpapi', config: nextConfig };
+  }
+  return { ok: false };
+}
+
+export function loadPackageTokenSecret(config = {}, platform = process.platform) {
+  if (platform === 'darwin') {
+    const result = run('security', [
+      'find-generic-password',
+      '-a',
+      PACKAGE_TOKEN_ACCOUNT,
+      '-s',
+      SERVICE,
+      '-w'
+    ]);
+    return result.status === 0 ? result.stdout.trim() : '';
+  }
+  if (platform === 'win32') {
+    const entry = config.secretStore?.[PACKAGE_TOKEN_ACCOUNT];
+    if (!entry || entry.provider !== 'windows-dpapi' || !entry.value) {
+      return '';
+    }
+    const result = run(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        '$secure = ConvertTo-SecureString -String $env:VENDIAN_SECRET_BLOB; $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure); try { [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }'
+      ],
+      { env: { ...process.env, VENDIAN_SECRET_BLOB: entry.value } }
+    );
+    return result.status === 0 ? result.stdout.trim() : '';
+  }
+  return '';
+}

package/src/setup.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import { loginWithVendianOAuth, saveCloudToken } from './auth.js';
+import { DEFAULT_GITLAB_HOST, DEFAULT_SDK_PUBLIC_PROJECT_ID, DEFAULT_SDK_RUNTIME_PROJECT_ID } from './constants.js';
+import { loadConfig, saveConfig, redact } from './config.js';
+import { installVendianPackages, registryConfig } from './install.js';
+import { managedVenvPath, venvVendian } from './paths.js';
+import { findPython, ensureVenv, pythonVersion, verifyVendianImports } from './python.js';
+import { savePackageTokenSecret } from './secret-store.js';
+
+export async function setup({
+  nonInteractive = false,
+  backend = undefined,
+  apiUrl = undefined,
+  noBrowser = false,
+  env = process.env,
+  platform = process.platform
+} = {}) {
+  const existing = loadConfig(env, platform);
+  const registry = registryConfig(existing, env, platform);
+  const next = {
+    ...existing,
+    gitlabHost: registry.gitlabHost || DEFAULT_GITLAB_HOST,
+    gitlabUsername: registry.username || '__token__',
+    sdkPublicProjectId: registry.sdkProjectId || DEFAULT_SDK_PUBLIC_PROJECT_ID,
+    sdkRuntimeProjectId: registry.runtimeProjectId || DEFAULT_SDK_RUNTIME_PROJECT_ID
+  };
+  let cloudAuthApiUrl;
+
+  console.log('Vendian setup');
+  console.log('This installs the private Vendian Python CLI/runtime into a managed local environment.');
+  console.log('Agent requirements.txt files stay reserved for agent-owned dependencies.');
+  console.log('');
+
+  if (!registry.token && !nonInteractive) {
+    console.log('Opening Vendian sign-in to get package access...');
+    const login = await loginWithVendianOAuth({ backend, apiUrl, noBrowser, env });
+    saveCloudToken(login, { env, platform });
+    cloudAuthApiUrl = login.apiUrl;
+    const packageCredentials = login.packageCredentials;
+    if (!packageCredentials?.token) {
+      throw new Error('Vendian login succeeded, but the backend did not return package credentials. Configure CLI_PACKAGE_REGISTRY_TOKEN on the backend.');
+    }
+    next.gitlabHost = packageCredentials.gitlabHost || next.gitlabHost;
+    next.gitlabUsername = packageCredentials.username || next.gitlabUsername;
+    next.sdkPublicProjectId = packageCredentials.sdkProjectId || next.sdkPublicProjectId;
+    next.sdkRuntimeProjectId = packageCredentials.runtimeProjectId || next.sdkRuntimeProjectId;
+    next.vendianAgentsVersion = packageCredentials.vendianAgentsVersion || next.vendianAgentsVersion;
+    next.vendianAgentsRuntimeVersion = packageCredentials.vendianAgentsRuntimeVersion || next.vendianAgentsRuntimeVersion;
+
+    const secret = savePackageTokenSecret(packageCredentials.token, next, platform);
+    if (secret.ok) {
+      Object.assign(next, secret.config || {});
+      delete next.gitlabToken;
+      console.log(`Package token saved with ${secret.provider}.`);
+    } else {
+      next.gitlabToken = packageCredentials.token;
+      console.log('Package token saved in the local Vendian CLI config file.');
+    }
+  } else if (registry.token) {
+    if (registry.tokenSource !== 'secret-store') {
+      next.gitlabToken = registry.token;
+    }
+    console.log(`Using GitLab package token ${redact(registry.token)}.`);
+  }
+
+  const installRegistry = registryConfig(next, env, platform);
+  if (!installRegistry.token) {
+    throw new Error('Setup needs package access. Run interactive `vendian login` to sign in, or set GITLAB_TOKEN for local development.');
+  }
+
+  const python = findPython(platform);
+  if (!python) {
+    throw new Error('Python 3.11+ was not found. Install Python 3.11 or newer, then rerun `vendian login`.');
+  }
+
+  const venvPath = managedVenvPath(env, platform);
+  console.log(`Managed environment: ${venvPath}`);
+  const pythonPath = ensureVenv(venvPath, python, platform);
+  console.log(`Python: ${pythonVersion(pythonPath) || pythonPath}`);
+
+  saveConfig(next, env, platform);
+  installVendianPackages({ pythonPath, venvPath, config: next, env, platform });
+  saveConfig({ ...next, lastManagedUpdateAt: new Date().toISOString() }, env, platform);
+
+  if (!verifyVendianImports(pythonPath)) {
+    throw new Error('Vendian packages installed, but import verification failed.');
+  }
+
+  const vendianPath = venvVendian(venvPath, platform);
+  if (!fs.existsSync(vendianPath)) {
+    throw new Error('Vendian executable was not found after install.');
+  }
+
+  console.log('');
+  for (const line of setupCompletionLines({ cloudAuthApiUrl, backend, apiUrl })) {
+    console.log(line);
+  }
+}
+
+export function setupCompletionLines({ cloudAuthApiUrl, backend, apiUrl } = {}) {
+  const lines = ['Vendian setup complete.'];
+  if (cloudAuthApiUrl) {
+    lines.push(`Cloud authentication saved for ${cloudAuthApiUrl}.`);
+    lines.push('Next: vendian cloud local serve --agents-dir ./agents');
+    return lines;
+  }
+
+  lines.push(`Next: ${cloudAuthLoginCommand({ backend, apiUrl })}`);
+  lines.push('Then: vendian cloud local serve --agents-dir ./agents');
+  return lines;
+}
+
+function cloudAuthLoginCommand({ backend, apiUrl } = {}) {
+  if (apiUrl) {
+    return `vendian cloud auth login --api-url ${apiUrl}`;
+  }
+  if (backend) {
+    return `vendian cloud auth login --backend ${backend}`;
+  }
+  return 'vendian cloud auth login';
+}