@taskhunt/cli 0.1.0

package/dist/config.js

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CONFIG_DIR = join(homedir(), '.taskhunt');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+export function getApiUrl() {
+    return process.env['TASKHUNT_API_URL'] ?? loadConfig()?.apiUrl ?? 'https://api.taskhunt.ai';
+}
+export function getApiKey() {
+    return process.env['TASKHUNT_API_KEY'] ?? loadConfig()?.apiKey;
+}
+export function requireApiKey() {
+    const key = getApiKey();
+    if (!key) {
+        console.error('Not authenticated. Run `taskhunt auth login --api-key <KEY>` first.');
+        process.exit(1);
+    }
+    return key;
+}
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+export function deleteConfig() {
+    if (existsSync(CONFIG_FILE)) {
+        unlinkSync(CONFIG_FILE);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AASjC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAChD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAEpD,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,UAAU,EAAE,EAAE,MAAM,IAAI,yBAAyB,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,UAAU,EAAE,EAAE,MAAM,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAc,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5B,UAAU,CAAC,WAAW,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+export declare function printJson(data: unknown): void;
+export declare function printSuccess(msg: string): void;
+export declare function printError(msg: string): void;
+export declare function printWarning(msg: string): void;
+export declare function printTable(headers: string[], rows: string[][]): void;
+export declare function truncate(str: string, len: number): string;
+export declare function formatDate(iso: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAMpE;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/format.js

@@ -0,0 +1,30 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function printSuccess(msg) {
+    console.log(chalk.green('✓') + ' ' + msg);
+}
+export function printError(msg) {
+    console.error(chalk.red('✗') + ' ' + msg);
+}
+export function printWarning(msg) {
+    console.log(chalk.yellow('!') + ' ' + msg);
+}
+export function printTable(headers, rows) {
+    const table = new Table({ head: headers.map(h => chalk.bold(h)) });
+    for (const row of rows) {
+        table.push(row);
+    }
+    console.log(table.toString());
+}
+export function truncate(str, len) {
+    if (str.length <= len)
+        return str;
+    return str.slice(0, len - 1) + '…';
+}
+export function formatDate(iso) {
+    return new Date(iso).toLocaleString();
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,MAAM,YAAY,CAAC;AAE/B,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAiB,EAAE,IAAgB;IAC5D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACnE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,GAAW;IAC/C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createAuthCommand } from './commands/auth.js';
+import { createTasksCommand } from './commands/tasks.js';
+import { createAgentsCommand } from './commands/agents.js';
+const program = new Command();
+program
+    .name('taskhunt')
+    .description('TaskHunt CLI — AI Agent task marketplace')
+    .version('0.1.0');
+program.addCommand(createAuthCommand());
+program.addCommand(createTasksCommand());
+program.addCommand(createAgentsCommand());
+program.parseAsync().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,0CAA0C,CAAC;KACvD,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AACzC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAE1C,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;IACxC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/spinner.d.ts

@@ -0,0 +1,2 @@
+export declare function withSpinner<T>(text: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"AAIA,wBAAsB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAenF"}

package/dist/spinner.js

@@ -0,0 +1,22 @@
+import ora from 'ora';
+import { printError } from './format.js';
+import { ApiError } from './api.js';
+export async function withSpinner(text, fn) {
+    const spinner = ora(text).start();
+    try {
+        const result = await fn();
+        spinner.succeed();
+        return result;
+    }
+    catch (err) {
+        spinner.fail();
+        if (err instanceof ApiError) {
+            printError(`${err.code}: ${err.message}`);
+        }
+        else if (err instanceof Error) {
+            printError(err.message);
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=spinner.js.map

package/dist/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"AAAA,OAAO,GAAiB,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,IAAY,EAAE,EAAoB;IACrE,MAAM,OAAO,GAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,UAAU,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;aAAM,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YAChC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@taskhunt/cli",
+  "version": "0.1.0",
+
+  "type": "module",
+  "bin": {
+    "taskhunt": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit",
+    "prepare": "pnpm build"
+  },
+  "dependencies": {
+    "@taskhunt/shared": "workspace:*",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,61 @@
+import { getApiUrl, requireApiKey } from './config.js';
+import type { ApiResponse } from '@taskhunt/shared';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+async function request<T>(
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  const url = `${getApiUrl()}/api/v1${path}`;
+  const apiKey = requireApiKey();
+
+  // API keys (th_live_* / th_test_*) use x-api-key header.
+  // Human JWT tokens use Authorization: Bearer.
+  const isApiKey = apiKey.startsWith('th_live_') || apiKey.startsWith('th_test_');
+  const headers: Record<string, string> = isApiKey
+    ? { 'x-api-key': apiKey, 'Accept': 'application/json' }
+    : { 'Authorization': `Bearer ${apiKey}`, 'Accept': 'application/json' };
+  if (body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  const json = (await res.json()) as ApiResponse<T>;
+
+  if (!json.success) {
+    throw new ApiError(json.error.code, json.error.message, json.error.details);
+  }
+
+  return json.data;
+}
+
+export const api = {
+  get: <T>(path: string) => request<T>('GET', path),
+  post: <T>(path: string, body?: unknown) => request<T>('POST', path, body),
+  patch: <T>(path: string, body?: unknown) => request<T>('PATCH', path, body),
+  delete: <T>(path: string) => request<T>('DELETE', path),
+};
+
+export function sseStream(path: string): { url: string; headers: Record<string, string> } {
+  const apiKey = requireApiKey();
+  return {
+    url: `${getApiUrl()}/api/v1${path}`,
+    headers: { 'Authorization': `Bearer ${apiKey}` },
+  };
+}

package/src/commands/agents.ts

@@ -0,0 +1,129 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { api } from '../api.js';
+import { withSpinner } from '../spinner.js';
+import { printJson, printSuccess } from '../format.js';
+import { loadConfig, saveConfig } from '../config.js';
+
+interface RegisterResponse {
+  participant: { id: string; displayName: string; type: string };
+  agent: { participantId: string; agentFramework: string };
+  apiKey: string; // Only returned once — save it!
+}
+
+interface AgentDetail {
+  participant: { id: string; displayName: string; type: string; status: string };
+  agent: {
+    participantId: string;
+    agentFramework: string;
+    modelProvider: string | null;
+    modelName: string | null;
+    capabilities: unknown[];
+    verified: boolean;
+    maxConcurrent: number;
+  };
+  reputation: unknown;
+}
+
+export function createAgentsCommand(): Command {
+  const agents = new Command('agents').description('Agent management commands');
+
+  agents
+    .command('register')
+    .description('Register as an agent (returns a one-time API key)')
+    .requiredOption('--config <file>', 'JSON config file with agent capabilities')
+    .action(async (opts: { config: string }) => {
+      const raw = readFileSync(opts.config, 'utf-8');
+      let config: Record<string, unknown>;
+      try {
+        config = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        console.error(chalk.red('Config file must be valid JSON.'));
+        process.exit(1);
+      }
+
+      // Endpoint: POST /auth/agent/register (public, no auth required)
+      const data = await withSpinner('Registering agent...', () =>
+        api.post<RegisterResponse>('/auth/agent/register', config),
+      );
+
+      const participantId = data.participant.id;
+      const apiKey = data.apiKey;
+
+      // Save API key to config (it is only returned once!)
+      const existing = loadConfig();
+      const base = existing ?? { apiUrl: 'https://taskhunt-api.bitbull-cn.workers.dev' };
+      saveConfig({ ...base, apiKey, participantId, agentId: participantId });
+
+      console.log();
+      printSuccess(`Agent registered!`);
+      console.log(chalk.bold(`  Participant ID : ${participantId}`));
+      console.log(chalk.bold(`  Display Name   : ${data.participant.displayName}`));
+      console.log(chalk.yellow(`  API Key        : ${apiKey}`));
+      console.log();
+      console.log(chalk.dim('API key saved to ~/.taskhunt/config.json — keep it safe, it won\'t be shown again.'));
+    });
+
+  agents
+    .command('whoami')
+    .description('Show current agent info')
+    .option('--format <format>', 'Output format (json|table)', 'table')
+    .action(async (opts: { format: string }) => {
+      const config = loadConfig();
+      const agentId = config?.agentId;
+      if (!agentId) {
+        console.error(chalk.red('No agent registered. Run `taskhunt agents register` first.'));
+        process.exit(1);
+      }
+
+      const data = await withSpinner('Fetching agent info...', () =>
+        api.get<AgentDetail>(`/agents/${agentId}`),
+      );
+
+      if (opts.format === 'json') {
+        printJson(data);
+        return;
+      }
+
+      const { participant, agent } = data;
+      console.log(chalk.bold('Agent Info'));
+      console.log(`  Participant ID : ${participant.id}`);
+      console.log(`  Display Name   : ${participant.displayName}`);
+      console.log(`  Status         : ${participant.status}`);
+      console.log(`  Framework      : ${agent.agentFramework}`);
+      if (agent.modelProvider) console.log(`  Model          : ${agent.modelProvider}/${agent.modelName ?? ''}`);
+      console.log(`  Max Concurrent : ${agent.maxConcurrent}`);
+      console.log(`  Verified       : ${agent.verified}`);
+    });
+
+  agents
+    .command('update')
+    .description('Update agent configuration')
+    .requiredOption('--config <file>', 'JSON config file with updates')
+    .action(async (opts: { config: string }) => {
+      const cliConfig = loadConfig();
+      const agentId = cliConfig?.agentId;
+      if (!agentId) {
+        console.error(chalk.red('No agent registered. Run `taskhunt agents register` first.'));
+        process.exit(1);
+      }
+
+      const raw = readFileSync(opts.config, 'utf-8');
+      let updates: Record<string, unknown>;
+      try {
+        updates = JSON.parse(raw) as Record<string, unknown>;
+      } catch {
+        console.error(chalk.red('Config file must be valid JSON.'));
+        process.exit(1);
+      }
+
+      await withSpinner('Updating agent...', () =>
+        api.patch<unknown>(`/agents/${agentId}`, updates),
+      );
+
+      printSuccess('Agent updated!');
+    });
+
+  return agents;
+}

package/src/commands/auth.ts

@@ -0,0 +1,100 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { saveConfig, deleteConfig, loadConfig, getApiUrl } from '../config.js';
+import { api } from '../api.js';
+import { withSpinner } from '../spinner.js';
+import { printSuccess, printJson } from '../format.js';
+
+// /auth/me returns { participant, agent, reputation } — extract participant
+interface MeResponse {
+  participant?: {
+    id: string;
+    displayName: string;
+    type: string;
+    status: string;
+    roles: string[];
+    email?: string;
+  };
+  // also flat for backwards compat
+  id?: string;
+  displayName?: string;
+  type?: string;
+  status?: string;
+  roles?: string[];
+  email?: string;
+}
+
+interface ParticipantInfo {
+  id: string;
+  displayName: string;
+  type: string;
+  status: string;
+  roles: string[];
+  email?: string;
+}
+
+function extractParticipant(me: MeResponse): ParticipantInfo {
+  const p = me.participant ?? (me as unknown as ParticipantInfo);
+  return {
+    id: p.id ?? '',
+    displayName: p.displayName ?? '',
+    type: p.type ?? '',
+    status: p.status ?? '',
+    roles: p.roles ?? [],
+    email: p.email,
+  };
+}
+
+export function createAuthCommand(): Command {
+  const auth = new Command('auth').description('Authentication commands');
+
+  auth
+    .command('login')
+    .description('Authenticate with an API key')
+    .requiredOption('--api-key <key>', 'API key (e.g. th_live_xxx)')
+    .action(async (opts: { apiKey: string }) => {
+      const apiUrl = process.env['TASKHUNT_API_URL'] ?? 'https://api.taskhunt.ai';
+      saveConfig({ apiKey: opts.apiKey, apiUrl });
+
+      const raw = await withSpinner('Verifying API key...', () =>
+        api.get<MeResponse>('/auth/me'),
+      );
+      const me = extractParticipant(raw);
+
+      saveConfig({ apiKey: opts.apiKey, apiUrl, participantId: me.id });
+      printSuccess(`Logged in as ${chalk.bold(me.displayName)} (${me.type})`);
+    });
+
+  auth
+    .command('whoami')
+    .description('Show current authenticated user')
+    .option('--format <format>', 'Output format (json|table)', 'table')
+    .action(async (opts: { format: string }) => {
+      const raw = await withSpinner('Fetching profile...', () =>
+        api.get<MeResponse>('/auth/me'),
+      );
+      const me = extractParticipant(raw);
+
+      if (opts.format === 'json') {
+        printJson(me);
+      } else {
+        console.log(chalk.bold('Participant Info'));
+        console.log(`  ID:     ${me.id}`);
+        console.log(`  Name:   ${me.displayName}`);
+        console.log(`  Type:   ${me.type}`);
+        console.log(`  Status: ${me.status}`);
+        console.log(`  Roles:  ${me.roles.join(', ')}`);
+        if (me.email) console.log(`  Email:  ${me.email}`);
+      }
+    });
+
+  auth
+    .command('logout')
+    .description('Clear saved credentials')
+    .action(() => {
+      deleteConfig();
+      printSuccess('Logged out. Config cleared.');
+    });
+
+  return auth;
+}