@thirdfy/agent-cli 0.1.36 → 0.1.37

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.37] - 2026-05-17
+
+### Added
+
+- Email OTP `thirdfy-agent login email` two-step onboarding (`send OTP` then `--code --accept-terms`) plus `help onboarding`, `doctor auth`, and `wallet list` so agents can learn and verify setup directly from the CLI.
+
+### Changed
+
+- `whoami` now reports masked auth, agent, and wallet profile state instead of dumping raw local config secrets.
+
+### Fixed
+
+- Onboarding help: neutral email-OTP wording, safer `maskSecret` for short tokens, and a non-interactive example that places `--ni` after `login email` so argv parsing does not swallow the `login` token.
+- `doctor auth`: agent API key is diagnostic-only (optional until execution); missing key no longer fails the command while the detail calls it optional.
+
 ## [0.1.36] - 2026-05-16
 
 ### Added

package/README.md

@@ -77,6 +77,13 @@ Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is c
 ### Login / logout / config UX
 
 ```bash
+# Email OTP first-run flow
+thirdfy-agent login email you@example.com --json
+thirdfy-agent login email you@example.com --code "<otp>" --accept-terms --key-name "My Agent" --json
+thirdfy-agent whoami --json
+thirdfy-agent wallet list --json
+thirdfy-agent doctor auth --json
+
 # Store auth defaults once
 thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$AGENT_API_KEY" --json
 
@@ -95,6 +102,8 @@ thirdfy-agent logout --json
 thirdfy-agent logout --all --json
 ```
 
+`login email` is a two-step headless-safe flow. Without `--code`, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With `--code --accept-terms`, it stores a short-lived owner session in `~/.thirdfy/config.json`, records linked EVM/Solana wallets when Privy returns them, and stores a new agent API key when first-run bootstrap issues one. Use `--not-interactive` / `--ni` in automation so missing input fails fast instead of prompting.
+
 `logout --all` is provider-agnostic: it attempts owner-session revocation when a session token exists, then always clears local credentials.
 
 ### Wallet-sign onboarding path

package/bin/thirdfy-agent.mjs

@@ -157,6 +157,9 @@ async function main() {
     case 'config set':
       await commandConfigSet(context, subFlags);
       return;
+    case 'login email':
+      await commandLoginEmail(context, { ...subFlags, address: parsed.positionals[2] });
+      return;
     case 'login':
       await commandLogin(context, subFlags);
       return;
@@ -164,11 +167,21 @@ async function main() {
       await commandLogout(context, subFlags);
       return;
     case 'whoami':
-      await commandProfileShow(context, subFlags);
+      await commandWhoami(context, subFlags);
       return;
     case 'doctor self':
       await commandDoctorSelf(context, subFlags);
       return;
+    case 'doctor auth':
+      await commandDoctorAuth(context, subFlags);
+      return;
+    case 'help onboarding':
+    case 'onboarding help':
+      await commandHelpOnboarding(context, subFlags);
+      return;
+    case 'wallet list':
+      await commandWalletList(context, subFlags);
+      return;
     default:
       break;
   }
@@ -361,6 +374,10 @@ function parseArgs(argv) {
   return { flags, positionals };
 }
 
+function isNonInteractive(flags = {}) {
+  return Boolean(flags.notInteractive || flags.ni || process.env.THIRDFY_NOT_INTERACTIVE === '1');
+}
+
 function toCamel(input) {
   return String(input || '')
     .trim()
@@ -2427,6 +2444,183 @@ async function commandProfileShow(ctx, _flags) {
   });
 }
 
+function maskSecret(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  if (raw.length <= 12) return '***';
+  if (raw.length <= 20) return `${raw.slice(0, 4)}***${raw.slice(-2)}`;
+  return `${raw.slice(0, 6)}...${raw.slice(-4)}`;
+}
+
+function buildOnboardingHelp(ctx) {
+  return {
+    title: 'Thirdfy Agent CLI onboarding',
+    summary: 'Use email OTP, wallet-sign, or existing credentials to create owner auth, wallets, and agent execution credentials.',
+    paths: [
+      {
+        id: 'email_otp',
+        recommended: true,
+        description: 'Email OTP first-run flow for humans and agents that can ask the user for a verification code.',
+        commands: [
+          'thirdfy-agent login email user@example.com',
+          'thirdfy-agent login email user@example.com --code <otp> --accept-terms --key-name "My Agent"',
+          'thirdfy-agent whoami',
+          'thirdfy-agent managed wallet init --chain-id 8453',
+        ],
+      },
+      {
+        id: 'wallet_sign',
+        description: 'Headless wallet proof for operators with an EVM signer.',
+        commands: [
+          'thirdfy-agent agent auth challenge --agent-key 0xYOUR_AGENT_KEY --json',
+          'thirdfy-agent login --agent-key 0xYOUR_AGENT_KEY --challenge-id <id> --signature <hex> --json',
+        ],
+      },
+      {
+        id: 'existing_credentials',
+        description: 'Use already-issued owner or agent credentials from a secure secret store.',
+        commands: [
+          'thirdfy-agent login --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"',
+          'thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN"',
+          'thirdfy-agent login --agent-api-key "$THIRDFY_AGENT_API_KEY"',
+        ],
+      },
+      {
+        id: 'mcp_bootstrap',
+        description: 'After owner proof, issue an MCP bootstrap token for agents.',
+        commands: [
+          'thirdfy-agent bootstrap complete --agent-key 0xYOUR_AGENT_KEY --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --lane thirdfy --json',
+        ],
+      },
+    ],
+    nonInteractive: {
+      flag: '--not-interactive or --ni',
+      example:
+        'thirdfy-agent login email user@example.com --code 123456 --accept-terms --ni (place --ni after the subcommand so it is not parsed as a flag value)',
+      rule: 'Commands must fail fast instead of waiting for prompts when required input is missing.',
+    },
+    apiBase: ctx.apiBase,
+  };
+}
+
+async function commandHelpOnboarding(ctx, _flags) {
+  printEnvelope({
+    success: true,
+    code: 'ONBOARDING_HELP_OK',
+    message: 'Thirdfy onboarding help',
+    data: buildOnboardingHelp(ctx),
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+async function commandWhoami(ctx, _flags) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
+  const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  printEnvelope({
+    success: true,
+    code: 'WHOAMI_OK',
+    message: 'Thirdfy CLI identity loaded',
+    data: {
+      profile: ctx.profile || config.profile || 'personal',
+      runMode: ctx.runMode || config.runMode || 'thirdfy',
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'thirdfy'),
+      auth: {
+        source: auth.source || null,
+        hasAuthToken: Boolean(auth.authToken),
+        hasOwnerSessionToken: Boolean(auth.ownerSessionToken),
+        ownerSessionToken: maskSecret(auth.ownerSessionToken),
+        ownerSessionExpiresAt: auth.ownerSessionExpiresAt || null,
+      },
+      agent: {
+        hasAgentApiKey: Boolean(agent.apiKey),
+        agentApiKey: maskSecret(agent.apiKey),
+        agentKey: agent.agentKey || null,
+      },
+      wallets: {
+        primaryEvmWallet: wallets.primaryEvmWallet || null,
+        evm: Array.isArray(wallets.evm) ? wallets.evm : [],
+        solana: Array.isArray(wallets.solana) ? wallets.solana : [],
+      },
+      configPath: getProfileConfigPath(),
+      nextSteps: buildOnboardingHelp(ctx).paths[0].commands,
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+async function commandWalletList(ctx, _flags) {
+  const config = loadProfileConfig();
+  const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  printEnvelope({
+    success: true,
+    code: 'WALLET_LIST_OK',
+    message: 'Linked wallets from local Thirdfy CLI profile',
+    data: {
+      primaryEvmWallet: wallets.primaryEvmWallet || null,
+      evm: Array.isArray(wallets.evm) ? wallets.evm : [],
+      solana: Array.isArray(wallets.solana) ? wallets.solana : [],
+      hint: 'Run `thirdfy-agent login email <email>` to refresh linked wallets from Privy-backed onboarding.',
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+async function commandDoctorAuth(ctx, _flags) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
+  const ownerSessionTokenFromEnv = String(process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  const authTokenFromEnv = String(process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  const agentApiKeyFromEnv = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
+  const checks = [
+    {
+      name: 'owner-auth',
+      ok: Boolean(auth.ownerSessionToken || auth.authToken || ownerSessionTokenFromEnv || authTokenFromEnv),
+      detail: auth.ownerSessionToken
+        ? 'owner session stored'
+        : auth.authToken
+          ? 'auth token stored'
+          : ownerSessionTokenFromEnv
+            ? 'owner session from THIRDFY_OWNER_SESSION_TOKEN'
+            : authTokenFromEnv
+              ? 'auth token from THIRDFY_AUTH_TOKEN'
+              : 'missing owner auth; run `thirdfy-agent login email <email>`',
+    },
+    {
+      name: 'agent-api-key',
+      optional: true,
+      ok: Boolean(agent.apiKey || agentApiKeyFromEnv),
+      detail: agent.apiKey
+        ? 'agent API key stored'
+        : agentApiKeyFromEnv
+          ? 'agent API key from THIRDFY_AGENT_API_KEY'
+          : 'not stored yet (optional until execution); complete onboarding or bootstrap to add one',
+    },
+    {
+      name: 'wallet-profile',
+      ok: Boolean(config.wallets?.primaryEvmWallet || (Array.isArray(config.wallets?.evm) && config.wallets.evm.length)),
+      detail: config.wallets?.primaryEvmWallet
+        || (Array.isArray(config.wallets?.evm) && config.wallets.evm.length
+          ? `${config.wallets.evm.length} linked EVM wallet${config.wallets.evm.length === 1 ? '' : 's'}`
+          : 'missing wallet profile; run email onboarding or wallet-sign proof'),
+    },
+  ];
+  const ok = checks.every((entry) => entry.optional || entry.ok);
+  printEnvelope({
+    success: ok,
+    code: ok ? 'DOCTOR_AUTH_OK' : 'DOCTOR_AUTH_NEEDS_SETUP',
+    message: ok ? 'Auth profile is ready' : 'Auth profile needs setup',
+    data: {
+      checks,
+      help: buildOnboardingHelp(ctx),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+  if (!ok) process.exit(1);
+}
+
 async function commandConfigSet(ctx, flags) {
   const key = String(flags.key || '').trim();
   const value = flags.value;
@@ -2577,6 +2771,149 @@ async function commandLogin(ctx, flags) {
   });
 }
 
+async function commandLoginEmail(ctx, flags) {
+  const current = loadProfileConfig();
+  const email = String(flags.address || flags.email || '').trim().toLowerCase();
+  if (!email) {
+    throw createCliError(
+      'LOGIN_EMAIL_REQUIRED',
+      isNonInteractive(flags)
+        ? 'Missing email address for non-interactive login. Use: thirdfy-agent login email user@example.com [--code <otp> --accept-terms]'
+        : 'Missing email address. Use: thirdfy-agent login email user@example.com'
+    );
+  }
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw createCliError('LOGIN_EMAIL_INVALID', 'Provide a valid email address for Thirdfy email login.');
+  }
+  const code = String(flags.code || flags.otp || '').trim();
+  const keyName = String(flags.keyName || 'Thirdfy CLI').trim();
+  if (!code) {
+    const response = await apiPost(ctx, '/api/v1/agent/onboarding/cli/email/start', {
+      email,
+      keyName,
+      requestedCapabilities: {
+        walletApi: true,
+        agentApi: true,
+        evmWallet: true,
+        solanaWallet: true,
+      },
+    });
+    const data = response?.data || response || {};
+    const next = {
+      ...current,
+      login: {
+        ...(current.login && typeof current.login === 'object' ? current.login : {}),
+        email: {
+          lastEmail: email,
+          lastAttemptId: data.loginAttemptId || null,
+          sentAt: new Date().toISOString(),
+        },
+      },
+    };
+    persistProfileConfig(next);
+    printEnvelope({
+      success: true,
+      code: 'LOGIN_EMAIL_CODE_SENT',
+      message: response?.message || 'Verification code sent',
+      data: {
+        email,
+        loginAttemptId: data.loginAttemptId || null,
+        expiresAt: data.expiresAt || null,
+        nextCommand: data.nextCommand || `thirdfy-agent login email ${email} --code <code> --accept-terms`,
+        configPath: getProfileConfigPath(),
+      },
+      meta: { apiBase: ctx.apiBase },
+    });
+    return;
+  }
+
+  if (!parseBooleanFlag(flags.acceptTerms, false)) {
+    throw createCliError(
+      'LOGIN_EMAIL_TERMS_REQUIRED',
+      'Email login requires --accept-terms to complete first-run onboarding.'
+    );
+  }
+
+  const lastAttempt = current?.login?.email && typeof current.login.email === 'object' ? current.login.email : {};
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/cli/email/complete', {
+    email,
+    code,
+    loginAttemptId: String(flags.loginAttemptId || lastAttempt.lastAttemptId || '').trim() || undefined,
+    acceptTerms: true,
+    keyName,
+    agentKey: String(flags.agentKey || '').trim() || undefined,
+    runMode: normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy'),
+    custodyMode: normalizeCustodyMode(
+      flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
+      normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy')
+    ),
+    bootstrapAgent: !parseBooleanFlag(flags.noBootstrapAgent, false),
+    rotateAgentKey: parseBooleanFlag(flags.rotateAgentKey, false),
+  });
+  const data = response?.data || response || {};
+  const ownerSessionToken = String(data.ownerSessionToken || '').trim();
+  const bootstrap = data.bootstrap && typeof data.bootstrap === 'object' ? data.bootstrap : {};
+  const agentApiKey = String(bootstrap.agentApiKey || '').trim();
+  const agentKey = String(bootstrap.agentKey || data.owner?.creatorWallet || '').trim();
+  const wallets = data.wallets && typeof data.wallets === 'object' ? data.wallets : {};
+  const primaryEvmWallet = String(wallets.primaryEvmWallet || data.owner?.creatorWallet || '').trim();
+  const persistedWallets = {
+    ...wallets,
+    ...(primaryEvmWallet ? { primaryEvmWallet } : {}),
+  };
+  const runMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy');
+  const custodyMode = normalizeCustodyMode(flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE, runMode);
+  if (!ownerSessionToken) {
+    throw createCliError('LOGIN_EMAIL_OWNER_SESSION_MISSING', 'Email onboarding completed without an owner session token.');
+  }
+  const next = {
+    ...current,
+    runMode,
+    custodyMode,
+    auth: {
+      ...(current.auth && typeof current.auth === 'object' ? current.auth : {}),
+      lastLoginAt: new Date().toISOString(),
+      source: 'email',
+      ownerSessionToken,
+      ownerSessionExpiresAt: data.ownerSessionExpiresAt || null,
+    },
+    wallets: persistedWallets,
+    login: {
+      ...(current.login && typeof current.login === 'object' ? current.login : {}),
+      email: {
+        lastEmail: email,
+        completedAt: new Date().toISOString(),
+      },
+    },
+  };
+  delete next.auth.authToken;
+  if (agentApiKey || agentKey) {
+    next.agent = {
+      ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
+      ...(agentApiKey ? { apiKey: agentApiKey } : {}),
+      ...(agentKey ? { agentKey } : {}),
+    };
+  }
+  persistProfileConfig(next);
+  printEnvelope({
+    success: true,
+    code: 'LOGIN_EMAIL_OK',
+    message: response?.message || 'Email login completed',
+    data: {
+      email,
+      hasOwnerSessionToken: Boolean(ownerSessionToken),
+      hasAgentApiKey: Boolean(agentApiKey),
+      agentKey: agentKey || null,
+      evmWallets: Array.isArray(persistedWallets.evm) ? persistedWallets.evm : [],
+      solanaWallets: Array.isArray(persistedWallets.solana) ? persistedWallets.solana : [],
+      primaryEvmWallet: persistedWallets.primaryEvmWallet || null,
+      configPath: getProfileConfigPath(),
+      nextSteps: response?.nextSteps || [],
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
 async function commandLogout(ctx, flags) {
   const current = loadProfileConfig();
   const localOnly = flags.all ? false : true;
@@ -4284,8 +4621,10 @@ Core commands:
   thirdfy-agent profile show [--json]
   thirdfy-agent config set --key <path> --value <value> [--json]
   thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--agent-key <key>] [--run-mode <mode>] [--custody-mode managed|external] [--wallet-address <addr>] [--json]
+  thirdfy-agent login email <address> [--code <otp>] [--accept-terms] [--key-name <name>] [--agent-key <key>] [--not-interactive|--ni] [--json]
   thirdfy-agent logout [--all] [--clear-agent-key] [--json]
   thirdfy-agent whoami [--json]
+  thirdfy-agent help onboarding [--json]
   thirdfy-agent catalogs list [--json]
   thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
   thirdfy-agent data summary --agent-key <key> [--chain-id <id>] [--network <id>] [--category trading|yield|prediction] [--limit <n>] [--json]
@@ -4308,6 +4647,7 @@ Core commands:
   thirdfy-agent managed wallet grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
   thirdfy-agent managed setup [--auth-token <token> | --owner-session-token <token>] --agent-key <key> [--run-mode thirdfy|hybrid|agent_wallet] [--token-address <addr>] [--max-usd-per-day <usd>] [--chain-id <id>] [--json]
   thirdfy-agent wallet execute --agent-api-key <key> --user-did <did> --action <id> --params <json> [--chain-id <id>] [--idempotency-key <key>] [--wallet-address <expected>] [--allow-wallet-mismatch] [--json]
+  thirdfy-agent wallet list [--json]
   thirdfy-agent wallet sign --agent-api-key <key> --action <id> --params <json> [--chain-id <id>] [--json]
   thirdfy-agent wallet submit --signed-tx-hex <hex> [--chain-id <id>] [--rpc-url <url>] [--json]
   thirdfy-agent agent run --agent-api-key <key> --action <id> --params <json> [--signer-method managed_wallet_server|byow|fanout_intent] [--strategy-intent single_wallet|fanout] [--run-mode <mode>] [--user-did <did>] [--json]
@@ -4327,6 +4667,7 @@ Core commands:
   thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--broadcast] [--idempotency-key <key>] [--json]
   thirdfy-agent self-exec --agent-api-key <key> --action <id> --params <json> --wallet-address <addr> --ows-wallet-name <name> [--rpc-url <url>] [--effect-check strict|relaxed|off] [--json]
   thirdfy-agent doctor self [--wallet-address <addr>] [--ows-wallet-name <name>] [--rpc-url <url>] [--json]
+  thirdfy-agent doctor auth [--json]
   thirdfy-agent jeff preflight --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
   thirdfy-agent jeff trade --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
   thirdfy-agent jeff status --intent-id <id> [--json]
@@ -4349,6 +4690,7 @@ Global flags:
   --allow-wallet-mismatch  bypass strict funded-wallet vs execution-wallet guard
   --effect-check <mode>  self-exec check mode: strict | relaxed | off (default: relaxed)
   --owner-session-token <token>  owner session token (or THIRDFY_OWNER_SESSION_TOKEN)
+  --not-interactive, --ni  fail fast when required login input is missing
   --json             stable machine-readable output
   --verbose          print adapter diagnostics
   --version          print version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {