trackly-cli 0.1.3 → 0.1.5

package/bin/trackly

@@ -1,44 +1,199 @@
 #!/usr/bin/env node
 'use strict';
 
-const { loadConfig, saveConfig, clearConfig, apiRequest, getToken, CONFIG_DIR } = require('../lib/client');
+const {
+  DEFAULT_BASE_URL,
+  apiRequest,
+  clearConfig,
+  getApiKey,
+  getAuthMethod,
+  getBaseUrl,
+  getConfigPaths,
+  hasAuth,
+  loadConfig,
+  saveConfig,
+} = require('../lib/client');
 const { color, isJSON, outputJobs, outputCompanies, outputStats, outputError } = require('../lib/formatters');
 const http = require('http');
 const crypto = require('crypto');
-const { execSync } = require('child_process');
-const path = require('path');
+const { spawnSync } = require('child_process');
+const { version: VERSION } = require('../package.json');
+
+const BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'version', 'v', 'clear-api-key', 'clear-base-url']);
+const VALUE_FLAGS = new Set([
+  'api-key',
+  'base-url',
+  'function',
+  'keywords',
+  'limit',
+  'location',
+  'modality',
+  'name',
+  'offset',
+  'sort',
+  'status',
+]);
+const AUTH_HELP_TEXT =
+  'Not authenticated. Run: trackly login or configure an API key with `trackly config --api-key <key>`';
+const STATUS_LABELS = {
+  applied: 'applied',
+  saved: 'saved',
+  dismissed: 'dismissed',
+};
 
 function parseArgs(args) {
   const result = { _: [], command: null };
-  let i = 0;
-  while (i < args.length && !args[i].startsWith('-')) {
-    if (!result.command) result.command = args[i];
-    else result._.push(args[i]);
-    i++;
-  }
-  while (i < args.length) {
+
+  for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+
+    if (arg === '--') {
+      result._.push(...args.slice(i + 1));
+      break;
+    }
+
+    if (arg === '-h') {
+      result.help = true;
+      continue;
+    }
+
+    if (arg === '-v') {
+      result.version = true;
+      continue;
+    }
+
     if (arg.startsWith('--')) {
+      const equalIndex = arg.indexOf('=');
+      if (equalIndex !== -1) {
+        const key = arg.slice(2, equalIndex);
+        const value = arg.slice(equalIndex + 1);
+        result[key] = value === '' ? true : value;
+        continue;
+      }
+
       const key = arg.slice(2);
-      if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
-        result[key] = args[i + 1]; i += 2;
-      } else { result[key] = true; i++; }
-    } else { result._.push(arg); i++; }
+      const nextArg = args[i + 1];
+      if (VALUE_FLAGS.has(key)) {
+        if (nextArg && !nextArg.startsWith('-')) {
+          result[key] = nextArg;
+          i++;
+        } else {
+          result[key] = null;
+        }
+        continue;
+      }
+
+      const expectsValue = !BOOLEAN_FLAGS.has(key) && nextArg && !nextArg.startsWith('-');
+
+      if (expectsValue) {
+        result[key] = nextArg;
+        i++;
+      } else {
+        result[key] = true;
+      }
+      continue;
+    }
+
+    if (!result.command) result.command = arg;
+    else result._.push(arg);
   }
+
   return result;
 }
 
+function failNow(message, exitCode = 1) {
+  outputError(message);
+  process.exit(exitCode);
+}
+
+function setErrorExit(message, exitCode = 1) {
+  outputError(message);
+  process.exitCode = exitCode;
+}
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function parseJobId(value) {
+  const normalized = String(value || '').trim();
+  if (!/^\d+$/.test(normalized)) return null;
+
+  const id = Number(normalized);
+  if (!Number.isSafeInteger(id) || id <= 0) return null;
+
+  return id;
+}
+
+function hasJobListFilters(args) {
+  return ['function', 'keywords', 'limit', 'location', 'modality', 'offset', 'sort', 'status']
+    .some((key) => args[key] !== undefined);
+}
+
+function openExternalUrl(url) {
+  let command = null;
+  let args = [];
+
+  if (process.platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (process.platform === 'linux') {
+    command = 'xdg-open';
+    args = [url];
+  } else if (process.platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '', url];
+  }
+
+  if (!command) return false;
+
+  const result = spawnSync(command, args, { stdio: 'ignore' });
+  return !result.error && result.status === 0;
+}
+
+function normalizeBaseUrlValue(rawValue) {
+  const value = String(rawValue || '').trim();
+  if (!value) {
+    throw new Error('Base URL cannot be empty');
+  }
+
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Base URL must start with http:// or https://');
+  }
+
+  return value.replace(/\/+$/, '');
+}
+
+function getPublicConfig() {
+  const config = loadConfig();
+  const { file } = getConfigPaths();
+  const authMethod = getAuthMethod();
+
+  return {
+    configFile: file,
+    baseUrl: getBaseUrl(),
+    authMethod: authMethod === 'apiKey' ? 'api_key' : authMethod || 'none',
+    hasApiKey: Boolean(getApiKey()),
+    hasToken: Boolean(config.token),
+    hasRefreshToken: Boolean(config.refreshToken),
+  };
+}
+
 // -- Commands --
 
 async function cmdLogin() {
   const port = 19847 + Math.floor(Math.random() * 1000);
-  const baseUrl = loadConfig().baseUrl || 'https://closeai.mba';
+  const baseUrl = getBaseUrl();
   const state = crypto.randomBytes(16).toString('hex');
 
   console.log(color('cyan', 'Opening browser for Google login...'));
   console.log(color('dim', `Callback server on port ${port}`));
 
   return new Promise((resolve, reject) => {
+    let settled = false;
+    let timeoutId = null;
+
     const server = http.createServer((req, res) => {
       const url = new URL(req.url, `http://localhost:${port}`);
       if (url.pathname === '/callback') {
@@ -46,10 +201,10 @@ async function cmdLogin() {
         if (returnedState !== state) {
           res.writeHead(403, { 'Content-Type': 'text/html' });
           res.end('<html><body><h2>Login failed. Invalid state parameter (possible CSRF).</h2></body></html>');
-          server.close();
-          reject(new Error('CSRF state mismatch'));
+          settle(new Error('CSRF state mismatch'));
           return;
         }
+
         const token = url.searchParams.get('token');
         const refreshToken = url.searchParams.get('refreshToken');
         if (token) {
@@ -57,13 +212,11 @@ async function cmdLogin() {
           res.writeHead(200, { 'Content-Type': 'text/html' });
           res.end('<html><body><h2>Logged in! You can close this tab.</h2><script>window.close()</script></body></html>');
           console.log(color('green', 'Login successful!'));
-          server.close();
-          resolve();
+          settle();
         } else {
           res.writeHead(400, { 'Content-Type': 'text/html' });
           res.end('<html><body><h2>Login failed. No token received.</h2></body></html>');
-          server.close();
-          reject(new Error('No token received'));
+          settle(new Error('No token received'));
         }
       } else {
         res.writeHead(404);
@@ -71,19 +224,34 @@ async function cmdLogin() {
       }
     });
 
+    const settle = (error = null) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+
+      const finish = () => {
+        if (error) reject(error);
+        else resolve();
+      };
+
+      if (server.listening) {
+        server.close(finish);
+      } else {
+        finish();
+      }
+    };
+
+    server.on('error', settle);
     server.listen(port, '127.0.0.1', () => {
       const loginUrl = `${baseUrl}/auth/google/cli?port=${port}&state=${state}`;
-      try {
-        if (process.platform === 'darwin') execSync(`open "${loginUrl}"`);
-        else if (process.platform === 'linux') execSync(`xdg-open "${loginUrl}"`);
-        else console.log(`Open this URL in your browser:\n${loginUrl}`);
-      } catch {
+      if (!openExternalUrl(loginUrl)) {
         console.log(`Open this URL in your browser:\n${loginUrl}`);
       }
     });
 
-    // Timeout after 2 minutes
-    setTimeout(() => { server.close(); reject(new Error('Login timed out')); }, 120000);
+    timeoutId = setTimeout(() => {
+      settle(new Error('Login timed out'));
+    }, 120000);
   });
 }
 
@@ -93,24 +261,30 @@ async function cmdLogout() {
 }
 
 async function cmdWhoami() {
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
     const result = await apiRequest('GET', '/api/auth/user');
-    if (result.success && result.user) {
-      if (isJSON()) return console.log(JSON.stringify(result.user, null, 2));
-      console.log(`${color('bold', result.user.name || 'Unknown')}`);
-      console.log(`  Email: ${color('cyan', result.user.email)}`);
-      console.log(`  ID: ${color('dim', result.user.id)}`);
+    const user = result.user || result;
+
+    if (result.success || result.user || result.email) {
+      if (isJSON()) return printJson(user);
+      console.log(`${color('bold', user.name || 'Unknown')}`);
+      console.log(`  Email: ${color('cyan', user.email)}`);
+      if (user.id !== undefined) {
+        console.log(`  ID: ${color('dim', user.id)}`);
+      }
     } else {
-      outputError('Not authenticated. Run: trackly login');
+      setErrorExit(AUTH_HELP_TEXT);
     }
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to get user info');
+    setErrorExit(e.error || e.message || 'Failed to get user info');
   }
 }
 
 async function cmdJobs(args) {
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   const params = new URLSearchParams();
   if (args.function) params.set('function', args.function);
   if (args.location) params.set('location', args.location);
@@ -125,19 +299,23 @@ async function cmdJobs(args) {
   try {
     const result = await apiRequest('GET', `/api/jobscout/jobs${qs ? '?' + qs : ''}`);
     outputJobs(result.jobs || result.data || []);
-    if (!isJSON() && result.total) console.log(color('dim', `Showing ${(result.jobs || result.data || []).length} of ${result.total} jobs`));
+    if (!isJSON() && result.total) {
+      console.log(color('dim', `Showing ${(result.jobs || result.data || []).length} of ${result.total} jobs`));
+    }
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to fetch jobs');
+    setErrorExit(e.error || e.message || 'Failed to fetch jobs');
   }
 }
 
 async function cmdJob(args) {
-  const id = args._[0];
-  if (!id) { outputError('Job ID required. Usage: trackly job <id>'); process.exit(1); }
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  const id = parseJobId(args._[0]);
+  if (id === null) failNow('Job ID must be a positive integer. Usage: trackly job <id>');
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
     const result = await apiRequest('GET', `/api/jobscout/jobs/${id}`);
-    if (isJSON()) return console.log(JSON.stringify(result, null, 2));
+    if (isJSON()) return printJson(result);
+
     const job = result.job || result;
     console.log(color('bold', job.title));
     console.log(`Company: ${color('blue', job.company_name)}`);
@@ -152,150 +330,220 @@ async function cmdJob(args) {
       if (job.description_text.length > 1000) console.log(color('dim', '... (truncated)'));
     }
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to fetch job');
+    setErrorExit(e.error || e.message || 'Failed to fetch job');
   }
 }
 
 async function cmdCompanies(args) {
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
+  const params = new URLSearchParams();
+  if (args.limit) params.set('limit', args.limit);
+  if (args.offset) params.set('offset', args.offset);
+
   try {
-    const result = await apiRequest('GET', '/api/jobscout/companies');
+    const qs = params.toString();
+    const result = await apiRequest('GET', `/api/jobscout/companies${qs ? '?' + qs : ''}`);
     outputCompanies(result.companies || result.data || []);
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to fetch companies');
+    setErrorExit(e.error || e.message || 'Failed to fetch companies');
   }
 }
 
 async function cmdSearch(args) {
-  const query = args._[0];
-  if (!query) { outputError('Search query required. Usage: trackly search "fintech"'); process.exit(1); }
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  const query = args._.join(' ').trim();
+  if (!query) failNow('Search query required. Usage: trackly search "fintech"');
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
     const result = await apiRequest('GET', `/api/jobscout/companies/search?q=${encodeURIComponent(query)}`);
     outputCompanies(result.companies || result.results || []);
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to search');
+    setErrorExit(e.error || e.message || 'Failed to search');
   }
 }
 
 async function cmdStats() {
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
     const result = await apiRequest('GET', '/api/jobscout/me');
     outputStats(result);
   } catch (e) {
-    outputError(e.error || e.message || 'Failed to fetch stats');
+    setErrorExit(e.error || e.message || 'Failed to fetch stats');
   }
 }
 
 async function cmdUpdateStatus(id, action) {
-  if (!id) { outputError(`Job ID required. Usage: trackly ${action} <id>`); process.exit(1); }
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  const jobId = parseJobId(id);
+  if (jobId === null) failNow(`Job ID must be a positive integer. Usage: trackly ${action} <id>`);
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
-    const result = await apiRequest('POST', '/api/jobscout-tracker/status', { jobId: parseInt(id), action });
-    if (isJSON()) return console.log(JSON.stringify(result, null, 2));
-    console.log(color('green', `Job ${id} marked as ${action}d`));
+    const result = await apiRequest('POST', '/api/jobscout-tracker/status', { jobId, action });
+    if (isJSON()) return printJson(result);
+    console.log(color('green', `Job ${jobId} marked as ${STATUS_LABELS[action]}.`));
   } catch (e) {
-    outputError(e.error || e.message || `Failed to ${action} job`);
+    setErrorExit(e.error || e.message || `Failed to ${action} job`);
   }
 }
 
 async function cmdAsk(args) {
   const query = args._.join(' ');
-  if (!query) { outputError('Query required. Usage: trackly ask "PM jobs at fintech"'); process.exit(1); }
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!query) failNow('Query required. Usage: trackly ask "PM jobs at fintech"');
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   try {
     const result = await apiRequest('GET', `/api/jobscout/ask?q=${encodeURIComponent(query)}`);
-    if (isJSON()) return console.log(JSON.stringify(result, null, 2));
+    if (isJSON()) return printJson(result);
+
     console.log(color('bold', 'Parsed filters:'));
     for (const [k, v] of Object.entries(result.parsedFilters || {})) {
       console.log(`  ${k}: ${color('cyan', String(v))}`);
     }
-    if (result.jobsUrl && result.jobsUrl.startsWith('/api/')) {
+
+    if (result.jobsUrl) {
       console.log();
       console.log(color('dim', `Fetching: ${result.jobsUrl}`));
-      // Auto-fetch jobs with parsed filters
       const jobsResult = await apiRequest('GET', result.jobsUrl);
       console.log();
       outputJobs(jobsResult.jobs || jobsResult.data || []);
     }
   } catch (e) {
-    if (e.status === 429) outputError('Daily limit reached (20 natural language queries per day)');
-    else outputError(e.error || e.message || 'Failed to process query');
+    if (e.status === 429) setErrorExit('Daily limit reached (20 natural language queries per day)');
+    else setErrorExit(e.error || e.message || 'Failed to process query');
   }
 }
 
 async function cmdApiKey(args) {
   const subcommand = args._[0] || 'create';
-  if (!getToken()) { outputError('Not logged in. Run: trackly login'); process.exit(1); }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
   if (subcommand === 'create') {
     const name = args.name || 'default';
     try {
       const result = await apiRequest('POST', '/api/auth/api-key', { name });
-      if (isJSON()) return console.log(JSON.stringify(result, null, 2));
+      if (isJSON()) return printJson(result);
       console.log(color('green', 'API key created!'));
       console.log();
       console.log(`Key: ${color('bold', result.key)}`);
       console.log(color('yellow', 'Save this key — it cannot be shown again.'));
+      console.log(color('dim', 'Tip: run `trackly config --api-key <key>` or set TRACKLY_API_KEY to use it.'));
     } catch (e) {
-      outputError(e.error || e.message || 'Failed to create API key');
+      setErrorExit(e.error || e.message || 'Failed to create API key');
     }
   } else if (subcommand === 'list') {
     try {
       const result = await apiRequest('GET', '/api/auth/api-keys');
-      if (isJSON()) return console.log(JSON.stringify(result.keys, null, 2));
+      if (isJSON()) return printJson(result.keys || []);
       for (const key of (result.keys || [])) {
         console.log(`${color('bold', key.key_prefix + '...')} — ${key.name} (created ${key.created_at})`);
       }
     } catch (e) {
-      outputError(e.error || e.message || 'Failed to list keys');
+      setErrorExit(e.error || e.message || 'Failed to list keys');
     }
+  } else {
+    failNow('Unknown api-key subcommand. Use: trackly api-key create | list');
   }
 }
 
+async function cmdConfig(args) {
+  if (args['api-key'] === null) failNow('API key value required. Usage: trackly config --api-key <key>');
+  if (args['base-url'] === null) failNow('Base URL value required. Usage: trackly config --base-url <url>');
+
+  const config = loadConfig();
+  let updated = false;
+
+  if (args['clear-api-key']) {
+    delete config.apiKey;
+    updated = true;
+    console.log(color('green', 'Stored API key cleared.'));
+  }
+
+  if (args['clear-base-url']) {
+    delete config.baseUrl;
+    updated = true;
+    console.log(color('green', `Base URL reset to default (${DEFAULT_BASE_URL}).`));
+  }
+
+  if (args['api-key'] !== undefined) {
+    config.apiKey = String(args['api-key']).trim();
+    updated = true;
+    console.log(color('green', 'API key saved. It will take precedence over OAuth tokens.'));
+  }
+
+  if (args['base-url'] !== undefined) {
+    config.baseUrl = normalizeBaseUrlValue(args['base-url']);
+    updated = true;
+    console.log(color('green', `Base URL set to ${config.baseUrl}.`));
+  }
+
+  if (updated) {
+    saveConfig(config);
+    console.log();
+  }
+
+  const publicConfig = getPublicConfig();
+  if (isJSON()) return printJson(publicConfig);
+
+  console.log(color('bold', 'Trackly Config'));
+  console.log(`Config file: ${color('dim', publicConfig.configFile)}`);
+  console.log(`Base URL: ${color('cyan', publicConfig.baseUrl)}`);
+  console.log(`Auth method: ${color('cyan', publicConfig.authMethod)}`);
+  console.log(`Stored API key: ${color(publicConfig.hasApiKey ? 'green' : 'dim', publicConfig.hasApiKey ? 'yes' : 'no')}`);
+  console.log(`Stored token: ${color(publicConfig.hasToken ? 'green' : 'dim', publicConfig.hasToken ? 'yes' : 'no')}`);
+  console.log(
+    `Refresh token: ${color(publicConfig.hasRefreshToken ? 'green' : 'dim', publicConfig.hasRefreshToken ? 'yes' : 'no')}`
+  );
+}
+
+async function cmdVersion() {
+  console.log(VERSION);
+}
+
 async function cmdMcp() {
-  // Delegate to MCP server
-  require('../mcp/server');
+  await require('../mcp/server').startMcpServer();
 }
 
 function showHelp() {
   console.log(`
-${color('bold', 'trackly')} — Trackly job tracker CLI + MCP server
+${color('bold', 'trackly')} v${VERSION} — Trackly job tracker CLI + MCP server
 
 ${color('bold', 'Usage:')}
   trackly <command> [options]
 
 ${color('bold', 'Commands:')}
-  ${color('cyan', 'login')}              Authenticate via Google OAuth
-  ${color('cyan', 'logout')}             Clear credentials
-  ${color('cyan', 'whoami')}             Show current user
-  ${color('cyan', 'jobs')}               List jobs (--function, --location, --modality, --status, --sort, --limit, --offset)
-  ${color('cyan', 'job <id>')}           Get full job detail
-  ${color('cyan', 'companies')}          List companies
-  ${color('cyan', 'search <query>')}     Semantic company search
-  ${color('cyan', 'stats')}              Show metrics dashboard
-  ${color('cyan', 'apply <id>')}         Mark job as applied
-  ${color('cyan', 'save <id>')}          Save a job
-  ${color('cyan', 'dismiss <id>')}       Dismiss a job
-  ${color('cyan', 'ask "query"')}        Natural language job search (20/day)
-  ${color('cyan', 'api-key create')}     Generate an API key
-  ${color('cyan', 'api-key list')}       List your API keys
-  ${color('cyan', 'mcp')}               Start MCP server (for Claude Code)
+  ${color('cyan', 'login')}                Authenticate via Google OAuth
+  ${color('cyan', 'logout')}               Clear credentials
+  ${color('cyan', 'whoami')}               Show current user
+  ${color('cyan', 'jobs')}                 List jobs (--function, --location, --modality, --status, --sort, --limit, --offset)
+  ${color('cyan', 'job <id>')}             Get full job detail
+  ${color('cyan', 'jobs <id>')}            Alias for job <id>
+  ${color('cyan', 'companies')}            List companies
+  ${color('cyan', 'companies search <q>')} Alias for semantic company search
+  ${color('cyan', 'search <query>')}       Semantic company search
+  ${color('cyan', 'stats')}                Show metrics dashboard
+  ${color('cyan', 'status')}               Alias for stats
+  ${color('cyan', 'apply <id>')}           Mark job as applied
+  ${color('cyan', 'save <id>')}            Save a job
+  ${color('cyan', 'dismiss <id>')}         Dismiss a job
+  ${color('cyan', 'ask "query"')}          Natural language job search (20/day)
+  ${color('cyan', 'api-key create')}       Generate an API key
+  ${color('cyan', 'api-key list')}         List your API keys
+  ${color('cyan', 'config')}               Show or update CLI config (--api-key, --base-url)
+  ${color('cyan', 'version')}              Show CLI version
+  ${color('cyan', 'mcp')}                  Start MCP server
 
 ${color('bold', 'Flags:')}
-  --json              Force JSON output
-  --help              Show this help
-
-${color('bold', 'MCP Setup (Claude Code):')}
-  Add to ~/.claude/settings.json:
-  {
-    "mcpServers": {
-      "trackly": {
-        "command": "trackly",
-        "args": ["mcp"]
-      }
-    }
-  }
+  --api-key <key>       Use an API key for this command
+  --base-url <url>      Override the Trackly API base URL for this command
+  --json                Force JSON output
+  --version             Show version
+  --help                Show this help
+
+${color('bold', 'MCP Setup:')}
+  Claude Code: claude mcp add-json trackly '{"command":"trackly","args":["mcp"]}'
+  Cursor: add {"command":"trackly","args":["mcp"]} to .cursor/mcp.json
 `);
 }
 
@@ -304,31 +552,107 @@ ${color('bold', 'MCP Setup (Claude Code):')}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
-  if (!args.command || args.help || args.h) { showHelp(); process.exit(0); }
+  if (args.command !== 'config' && args['api-key'] === null) {
+    failNow('API key value required. Usage: trackly --api-key <key> <command>');
+  }
+
+  if (args.command !== 'config' && args['base-url'] === null) {
+    failNow('Base URL value required. Usage: trackly --base-url <url> <command>');
+  }
+
+  if (args.command !== 'config' && args['api-key']) {
+    process.env.TRACKLY_API_KEY = String(args['api-key']);
+  }
+
+  if (args.command !== 'config' && args['base-url']) {
+    process.env.TRACKLY_BASE_URL = normalizeBaseUrlValue(args['base-url']);
+  }
+
+  if (args.version || args.v || args.command === 'version') {
+    await cmdVersion();
+    return;
+  }
+
+  if (!args.command || args.help || args.h) {
+    showHelp();
+    process.exit(0);
+  }
 
   switch (args.command) {
-    case 'login': await cmdLogin(); break;
-    case 'logout': await cmdLogout(); break;
-    case 'whoami': await cmdWhoami(); break;
-    case 'jobs': await cmdJobs(args); break;
-    case 'job': await cmdJob(args); break;
-    case 'companies': await cmdCompanies(args); break;
-    case 'search': await cmdSearch(args); break;
-    case 'stats': await cmdStats(); break;
-    case 'apply': await cmdUpdateStatus(args._[0], 'applied'); break;
-    case 'save': await cmdUpdateStatus(args._[0], 'saved'); break;
-    case 'dismiss': await cmdUpdateStatus(args._[0], 'dismissed'); break;
-    case 'ask': await cmdAsk(args); break;
-    case 'api-key': await cmdApiKey(args); break;
-    case 'mcp': await cmdMcp(); break;
+    case 'login':
+      await cmdLogin();
+      break;
+    case 'logout':
+      await cmdLogout();
+      break;
+    case 'whoami':
+      await cmdWhoami();
+      break;
+    case 'jobs':
+      if (parseJobId(args._[0]) !== null && !hasJobListFilters(args)) {
+        await cmdJob({ ...args, _: [args._[0]] });
+      } else {
+        await cmdJobs(args);
+      }
+      break;
+    case 'job':
+      await cmdJob(args);
+      break;
+    case 'companies':
+      if (args._[0] === 'search') {
+        await cmdSearch({ ...args, _: args._.slice(1) });
+      } else {
+        await cmdCompanies(args);
+      }
+      break;
+    case 'search':
+      await cmdSearch(args);
+      break;
+    case 'stats':
+    case 'status':
+      await cmdStats();
+      break;
+    case 'apply':
+      await cmdUpdateStatus(args._[0], 'applied');
+      break;
+    case 'save':
+      await cmdUpdateStatus(args._[0], 'saved');
+      break;
+    case 'dismiss':
+      await cmdUpdateStatus(args._[0], 'dismissed');
+      break;
+    case 'ask':
+      await cmdAsk(args);
+      break;
+    case 'api-key':
+      await cmdApiKey(args);
+      break;
+    case 'config':
+      await cmdConfig(args);
+      break;
+    case 'mcp':
+      await cmdMcp();
+      break;
     default:
-      outputError(`Unknown command: ${args.command}`);
+      setErrorExit(`Unknown command: ${args.command}`);
       showHelp();
       process.exit(1);
   }
 }
 
-main().catch(e => {
-  outputError(e.message || String(e));
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((e) => {
+    outputError(e.message || String(e));
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  getPublicConfig,
+  hasJobListFilters,
+  main,
+  normalizeBaseUrlValue,
+  openExternalUrl,
+  parseArgs,
+  parseJobId,
+};