@techdigger/humanode-agentlink-cli 0.2.0 → 0.3.0

package/REGISTRATION.md

@@ -1,10 +1,10 @@
-# Biomapper Link — Agent Developer Guide
+# Humanode Agentlink — Agent Developer Guide
 
 Link your AI agent to a biomapped human and unlock free or discounted access to x402 APIs.
 
 ## What linking does
 
-When your agent is linked to a biomapped owner, platforms using Biomapper Link can identify your agent as acting on behalf of a real human. This unlocks better pricing: free tiers, free trials, or discounts that are unavailable to unlinked agents.
+When your agent is linked to a biomapped owner, platforms using Humanode Agentlink can identify your agent as acting on behalf of a real human. This unlocks better pricing: free tiers, free trials, or discounts that are unavailable to unlinked agents.
 
 ## Prerequisites
 

package/dist/commands/init.js

@@ -30,20 +30,21 @@ export async function runInit(options, depsInput = {}) {
     const cwd = depsInput.cwd ?? process.cwd();
     const env = depsInput.env ?? process.env;
     const installDependencies = depsInput.installProjectDependencies ?? installProjectDependencies;
-    const prompter = depsInput.prompter ?? createConsolePrompter();
+    let _prompter = depsInput.prompter;
+    const getPrompter = () => (_prompter ??= createConsolePrompter());
     try {
-        const rawDirectory = await resolveInteractiveValue(options.directory, options.yes, () => DEFAULT_PROJECT_DIR, () => prompter.text({
+        const rawDirectory = await resolveInteractiveValue(options.directory, options.yes, () => DEFAULT_PROJECT_DIR, () => getPrompter().text({
             message: 'Project directory',
             defaultValue: DEFAULT_PROJECT_DIR,
         }));
         const targetDir = path.resolve(cwd, rawDirectory);
         await ensureTargetDirectoryIsWritable(targetDir);
-        const template = await resolveInteractiveValue(options.template, options.yes, () => 'langchain', () => prompter.select({
+        const template = await resolveInteractiveValue(options.template, options.yes, () => 'langchain', () => getPrompter().select({
             message: 'Starter template',
             options: TEMPLATE_NAMES.map(value => ({ value, label: value })),
             defaultValue: 'langchain',
         }));
-        const network = await resolveInteractiveValue(options.network, options.yes, () => resolveNetwork(undefined, env), () => prompter.select({
+        const network = await resolveInteractiveValue(options.network, options.yes, () => resolveNetwork(undefined, env), () => getPrompter().select({
             message: 'Biomapper network',
             options: [
                 { value: 'base-sepolia', label: 'base-sepolia' },
@@ -51,11 +52,11 @@ export async function runInit(options, depsInput = {}) {
             ],
             defaultValue: resolveNetwork(undefined, env),
         }));
-        const registry = await resolveInteractiveValue(options.registry, options.yes, () => env.BIOMAPPER_REGISTRY ?? DEFAULT_REGISTRY, async () => parseAddressOrPlaceholder('registry', await prompter.text({
+        const registry = await resolveInteractiveValue(options.registry, options.yes, () => env.BIOMAPPER_REGISTRY ?? DEFAULT_REGISTRY, async () => parseAddressOrPlaceholder('registry', await getPrompter().text({
             message: 'Biomapper registry address',
             defaultValue: env.BIOMAPPER_REGISTRY ?? DEFAULT_REGISTRY,
         }), DEFAULT_REGISTRY));
-        const packageManager = await resolveInteractiveValue(options.packageManager, options.yes, () => 'npm', () => prompter.select({
+        const packageManager = await resolveInteractiveValue(options.packageManager, options.yes, () => 'npm', () => getPrompter().select({
             message: 'Package manager',
             options: PACKAGE_MANAGERS.map(value => ({ value, label: value })),
             defaultValue: 'npm',
@@ -65,7 +66,7 @@ export async function runInit(options, depsInput = {}) {
             ? true
             : options.yes
                 ? false
-                : await prompter.confirm({
+                : await getPrompter().confirm({
                     message: 'Install dependencies now',
                     defaultValue: true,
                 });
@@ -102,7 +103,7 @@ export async function runInit(options, depsInput = {}) {
     }
     finally {
         if (!depsInput.prompter) {
-            prompter?.close();
+            _prompter?.close();
         }
     }
 }

package/dist/commands/keystore.d.ts

@@ -0,0 +1,3 @@
+export declare function runKeystoreSet(): Promise<string>;
+export declare function runKeystoreDelete(): Promise<void>;
+export declare function runKeystoreAddress(): Promise<string>;

package/dist/commands/keystore.js

@@ -0,0 +1,37 @@
+import { privateKeyToAccount } from 'viem/accounts';
+import { CliError, normalizePrivateKey, readPassword } from '../lib/core.js';
+import { decryptKeystore, deleteKeystore, encryptAndSave, keystoreExists, keystorePath } from '../lib/keystore.js';
+export async function runKeystoreSet() {
+    const exists = await keystoreExists();
+    if (exists) {
+        throw new CliError(`A keystore already exists at ${keystorePath()}.\nRun "agentlink keystore delete" first to replace it.`);
+    }
+    const rawKey = await readPassword('Agent private key (hidden): ');
+    if (!rawKey.trim()) {
+        throw new CliError('No private key provided.');
+    }
+    const privateKey = normalizePrivateKey(rawKey.trim());
+    const address = privateKeyToAccount(privateKey).address;
+    const password = await readPassword('Keystore password (hidden): ');
+    if (!password) {
+        throw new CliError('Password cannot be empty.');
+    }
+    const confirm = await readPassword('Confirm password (hidden): ');
+    if (password !== confirm) {
+        throw new CliError('Passwords do not match.');
+    }
+    await encryptAndSave(privateKey, password);
+    return address;
+}
+export async function runKeystoreDelete() {
+    const exists = await keystoreExists();
+    if (!exists) {
+        throw new CliError('No keystore found.');
+    }
+    await deleteKeystore();
+}
+export async function runKeystoreAddress() {
+    const password = await readPassword('Keystore password (hidden): ');
+    const privateKey = normalizePrivateKey(await decryptKeystore(password));
+    return privateKeyToAccount(privateKey).address;
+}

package/dist/help.d.ts

@@ -1,4 +1,5 @@
 export declare function getRootHelpText(): string;
+export declare function getKeystoreHelpText(): string;
 export declare function getAuthorizeLinkHelpText(): string;
 export declare function getStatusHelpText(): string;
 export declare function getLinkHelpText(): string;

package/dist/help.js

@@ -2,19 +2,21 @@ export function getRootHelpText() {
     return `Usage: agentlink <command> [options]
 
 Commands:
+  keystore         Manage the encrypted agent private key keystore
   init             Scaffold a Biomapper-ready agent starter
-  link             Generate consent and open a self-contained local/dev linker URL
+  link             Generate consent and open a linker URL for owner approval
   authorize-link   Generate a one-time EIP-712 consent blob for manual linking
   status           Check whether an agent is linked and active
 
+Flags:
+  --help, -h       Show this help text
+
 Run agentlink <command> --help for command-specific options.
 
 Environment:
-  AGENT_PRIVATE_KEY    Local/dev secret source; prefer stdin or secret managers in production
   BIOMAPPER_NETWORK    Default network (base | base-sepolia)
   BIOMAPPER_REGISTRY   Default BiomapperAgentRegistry address
   BIOMAPPER_RPC_URL    Optional RPC URL override
-  BIOMAPPER_LINKER_URL Default linker URL (defaults to http://localhost:5173/)
   AGENTLINK_TELEMETRY   Optional override for the saved CLI telemetry choice (on | off)
   AGENTLINK_POSTHOG_KEY Optional PostHog API key for CLI telemetry
   AGENTLINK_POSTHOG_HOST Optional PostHog host override (defaults to https://us.i.posthog.com)
@@ -23,6 +25,25 @@ Environment:
   AGENTLINK_CONTENT_ID  Optional content identifier for telemetry events
 `;
 }
+export function getKeystoreHelpText() {
+    return `Usage: agentlink keystore <subcommand>
+
+Description:
+  Manage an AES-256-GCM encrypted keystore for your agent private key.
+  The key is stored at ~/.agentlink/keystore.json, readable only by your user.
+  All commands that need the private key unlock it automatically at runtime.
+
+Subcommands:
+  set      Store your agent private key (prompts for key + password, never logged)
+  delete   Remove the keystore
+  address  Show the agent address derived from the stored key (prompts for password)
+
+Examples:
+  agentlink keystore set
+  agentlink keystore address
+  agentlink keystore delete
+`;
+}
 export function getAuthorizeLinkHelpText() {
     return `Usage:
   agentlink authorize-link --owner <address> [options]
@@ -36,10 +57,12 @@ Options:
   --registry     BiomapperAgentRegistry contract address (falls back to BIOMAPPER_REGISTRY)
   --deadline     Unix timestamp in seconds for signature expiry
   --network      base | base-sepolia (default: BIOMAPPER_NETWORK or base-sepolia)
-  --private-key  Insecure/dev-only: agent private key as 0x-prefixed hex. Falls back to AGENT_PRIVATE_KEY
-  --private-key-stdin  Read the agent private key from stdin instead of argv
+  --private-key-stdin  Read the agent private key from stdin (for CI/secret managers)
+  --private-key  Dev-only: pass key directly as 0x-prefixed hex. Prefer keystore or stdin.
   --rpc-url      Optional RPC URL override for the selected network
   --help         Show this help message
+
+Key resolution order: keystore (default) → --private-key-stdin → --private-key → AGENT_PRIVATE_KEY env
 `;
 }
 export function getStatusHelpText() {
@@ -52,13 +75,15 @@ Description:
 
 Options:
   --registry     BiomapperAgentRegistry contract address (falls back to BIOMAPPER_REGISTRY)
-  --agent        Agent wallet address to check. If omitted, derived from the private key input
+  --agent        Agent wallet address to check (skips key lookup entirely)
   --network      base | base-sepolia (default: BIOMAPPER_NETWORK or base-sepolia)
-  --private-key  Insecure/dev-only: agent private key (used to derive agent address if --agent is omitted)
-  --private-key-stdin  Read the agent private key from stdin instead of argv
+  --private-key-stdin  Read the agent private key from stdin (for CI/secret managers)
+  --private-key  Dev-only: pass key directly as 0x-prefixed hex
   --rpc-url      Optional RPC URL override for the selected network
   --json         Output raw JSON instead of human-readable text
   --help         Show this help message
+
+Key resolution order: keystore (default) → --private-key-stdin → --private-key → AGENT_PRIVATE_KEY env
 `;
 }
 export function getLinkHelpText() {
@@ -74,10 +99,10 @@ Options:
   --registry     BiomapperAgentRegistry contract address (falls back to BIOMAPPER_REGISTRY)
   --network      base | base-sepolia (default: BIOMAPPER_NETWORK or base-sepolia)
   --deadline     Unix timestamp in seconds for signature and session expiry (default: 24 hours from now)
-  --private-key  Insecure/dev-only: agent private key as 0x-prefixed hex. Falls back to AGENT_PRIVATE_KEY
-  --private-key-stdin  Read the agent private key from stdin instead of argv
+  --private-key-stdin  Read the agent private key from stdin (for CI/secret managers)
+  --private-key  Dev-only: pass key directly as 0x-prefixed hex
   --rpc-url      Optional RPC URL override for the selected network
-  --linker-url   Linker base URL (default: BIOMAPPER_LINKER_URL or http://localhost:5173/)
+  --linker-url   Linker base URL override (default: https://agent-kit-biomapper.vercel.app/)
   --open         Open the generated linker URL in the default browser
   --json         Output consent, session, and linker URL as JSON
   --help         Show this help message

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export interface CliRuntime {
     buildLinkUrl: (baseUrl: string, session: Awaited<ReturnType<typeof createLinkSession>>) => string;
     openUrl: (url: string) => Promise<void>;
     readStdin: () => Promise<string>;
+    readPassword: (prompt: string) => Promise<string>;
 }
 export declare function runCli(argv?: string[], overrides?: Partial<CliRuntime>): Promise<number>;

package/dist/index.js

@@ -6,8 +6,11 @@ import { formatInitOutput, parseInitOptions, runInit } from './commands/init.js'
 import { formatLinkOutput, parseLinkOptions, runLink } from './commands/link.js';
 import { formatStatusOutput, parseStatusOptions, runStatus } from './commands/status.js';
 import { parseAuthorizeLinkOptions, runAuthorizeLink } from './commands/authorize-link.js';
-import { CliError, formatJson, loadEnvFiles, openUrlInBrowser, parseFlags, readAllFromStdin } from './lib/core.js';
-import { getAuthorizeLinkHelpText, getInitHelpText, getLinkHelpText, getRootHelpText, getStatusHelpText, } from './help.js';
+import { runKeystoreAddress, runKeystoreDelete, runKeystoreSet } from './commands/keystore.js';
+import { CliError, formatJson, loadEnvFiles, openUrlInBrowser, parseFlags, readAllFromStdin, readPassword } from './lib/core.js';
+import { decryptKeystore, keystoreExists, keystorePath } from './lib/keystore.js';
+import { getAuthorizeLinkHelpText, getInitHelpText, getKeystoreHelpText, getLinkHelpText, getRootHelpText, getStatusHelpText, } from './help.js';
+import { VERSION } from './version.js';
 import { buildEmbeddedHostedLinkUrl, createAgentLinkConsent, createBiomapperQueryClient, createLinkSession, } from '@techdigger/humanode-agentlink';
 function writeLine(write, text) {
     write(text.endsWith('\n') ? text : `${text}\n`);
@@ -30,6 +33,7 @@ export async function runCli(argv = process.argv.slice(2), overrides = {}) {
         buildLinkUrl: overrides.buildLinkUrl ?? buildEmbeddedHostedLinkUrl,
         openUrl: overrides.openUrl ?? openUrlInBrowser,
         readStdin: overrides.readStdin ?? readAllFromStdin,
+        readPassword: overrides.readPassword ?? readPassword,
     };
     const [command, ...args] = argv;
     try {
@@ -37,7 +41,42 @@ export async function runCli(argv = process.argv.slice(2), overrides = {}) {
             writeLine(runtime.stdout, getRootHelpText());
             return 0;
         }
+        if (command === '--version' || command === '-v') {
+            writeLine(runtime.stdout, VERSION);
+            return 0;
+        }
         switch (command) {
+            case 'keystore': {
+                const [subcommand, ...subArgs] = args;
+                if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+                    writeLine(runtime.stdout, getKeystoreHelpText());
+                    return 0;
+                }
+                switch (subcommand) {
+                    case 'set': {
+                        if (subArgs.includes('--help') || subArgs.includes('-h')) {
+                            writeLine(runtime.stdout, getKeystoreHelpText());
+                            return 0;
+                        }
+                        const address = await runKeystoreSet();
+                        writeLine(runtime.stdout, `Keystore saved at ${keystorePath()}`);
+                        writeLine(runtime.stdout, `Agent address: ${address}`);
+                        return 0;
+                    }
+                    case 'delete': {
+                        await runKeystoreDelete();
+                        writeLine(runtime.stdout, 'Keystore deleted.');
+                        return 0;
+                    }
+                    case 'address': {
+                        const address = await runKeystoreAddress();
+                        writeLine(runtime.stdout, `Agent address: ${address}`);
+                        return 0;
+                    }
+                    default:
+                        throw new CliError(`Unknown keystore subcommand "${subcommand}". Run "agentlink keystore --help" for available subcommands.`);
+                }
+            }
             case 'authorize-link':
                 if (args.includes('--help') || args.includes('-h')) {
                     writeLine(runtime.stdout, getAuthorizeLinkHelpText());
@@ -155,17 +194,26 @@ export async function runCli(argv = process.argv.slice(2), overrides = {}) {
 }
 async function readPrivateKeyFromStdin(argv, runtime) {
     const parsed = parseFlags(argv);
-    if (!parsed.flags.has('private-key-stdin')) {
-        return undefined;
+    if (parsed.flags.has('private-key-stdin')) {
+        if (parsed.values['private-key']) {
+            throw new CliError('Pass either --private-key or --private-key-stdin, not both.');
+        }
+        const privateKey = (await runtime.readStdin()).trim();
+        if (!privateKey) {
+            throw new CliError('Missing agent private key on stdin. Pipe a 32-byte hex key into --private-key-stdin.');
+        }
+        return privateKey;
     }
-    if (parsed.values['private-key']) {
-        throw new CliError('Pass either --private-key or --private-key-stdin, not both.');
+    // If an explicit key source is already present, let resolvePrivateKey handle it
+    if (parsed.values['private-key'] || runtime.env.AGENT_PRIVATE_KEY) {
+        return undefined;
     }
-    const privateKey = (await runtime.readStdin()).trim();
-    if (!privateKey) {
-        throw new CliError('Missing agent private key on stdin. Pipe a 32-byte hex key into --private-key-stdin.');
+    // Fall back to keystore
+    if (await keystoreExists()) {
+        const password = await runtime.readPassword('Keystore password: ');
+        return await decryptKeystore(password);
     }
-    return privateKey;
+    return undefined;
 }
 function isExecutedDirectly() {
     if (!process.argv[1]) {

package/dist/lib/core.d.ts

@@ -67,6 +67,7 @@ export declare function parseAddressOrPlaceholder(name: string, value: string |
 export declare function resolveRegistryAddress(value: string | undefined, env: EnvSource): Address;
 export declare function resolveRpcUrl(value: string | undefined, env: EnvSource): string | undefined;
 export declare function resolveLinkerUrl(value: string | undefined, env: EnvSource): string;
+export declare function readPassword(prompt: string): Promise<string>;
 export declare function normalizePrivateKey(value: string | undefined): Hex;
 export declare function resolvePrivateKey(value: string | undefined, env: EnvSource, override?: string): Hex;
 export declare function deriveAgentAddress(privateKey: Hex): Address;

package/dist/lib/core.js

@@ -134,7 +134,46 @@ export function resolveRpcUrl(value, env) {
     return value ?? env.BIOMAPPER_RPC_URL;
 }
 export function resolveLinkerUrl(value, env) {
-    return value ?? env.BIOMAPPER_LINKER_URL ?? 'http://localhost:5173/';
+    return value ?? env.BIOMAPPER_LINKER_URL ?? 'https://agent-kit-biomapper.vercel.app/';
+}
+export function readPassword(prompt) {
+    return new Promise((resolve, reject) => {
+        if (!process.stdin.isTTY) {
+            reject(new CliError('Cannot read keystore password: not a TTY. Set AGENT_PRIVATE_KEY or use --private-key-stdin in non-interactive environments.'));
+            return;
+        }
+        process.stdout.write(prompt);
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+        let password = '';
+        const onData = (char) => {
+            switch (char) {
+                case '\n':
+                case '\r':
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stdin.removeListener('data', onData);
+                    process.stdout.write('\n');
+                    resolve(password);
+                    break;
+                case '\u0003':
+                    // Ctrl+C
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stdin.removeListener('data', onData);
+                    reject(new CliError('Cancelled.'));
+                    break;
+                case '\u007F':
+                    // Backspace
+                    password = password.slice(0, -1);
+                    break;
+                default:
+                    password += char;
+            }
+        };
+        process.stdin.on('data', onData);
+    });
 }
 export function normalizePrivateKey(value) {
     if (!value) {

package/dist/lib/keystore.d.ts

@@ -0,0 +1,5 @@
+export declare function keystorePath(): string;
+export declare function keystoreExists(): Promise<boolean>;
+export declare function encryptAndSave(privateKey: string, password: string): Promise<void>;
+export declare function decryptKeystore(password: string): Promise<string>;
+export declare function deleteKeystore(): Promise<void>;

package/dist/lib/keystore.js

@@ -0,0 +1,81 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+const KEYSTORE_VERSION = 1;
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEY_LEN = 32;
+export function keystorePath() {
+    return path.join(os.homedir(), '.agentlink', 'keystore.json');
+}
+export async function keystoreExists() {
+    try {
+        await readFile(keystorePath());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function deriveKey(password, salt) {
+    return scryptSync(password, salt, KEY_LEN, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
+}
+export async function encryptAndSave(privateKey, password) {
+    const salt = randomBytes(32);
+    const iv = randomBytes(12);
+    const key = deriveKey(password, salt);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(privateKey, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const data = {
+        version: KEYSTORE_VERSION,
+        salt: salt.toString('hex'),
+        iv: iv.toString('hex'),
+        tag: tag.toString('hex'),
+        ciphertext: ciphertext.toString('hex'),
+    };
+    const filePath = keystorePath();
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+export async function decryptKeystore(password) {
+    let raw;
+    try {
+        raw = await readFile(keystorePath(), 'utf8');
+    }
+    catch {
+        throw new Error('No keystore found. Run "agentlink keystore set" first.');
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Keystore file is corrupted.');
+    }
+    try {
+        const salt = Buffer.from(data.salt, 'hex');
+        const iv = Buffer.from(data.iv, 'hex');
+        const tag = Buffer.from(data.tag, 'hex');
+        const ciphertext = Buffer.from(data.ciphertext, 'hex');
+        const key = deriveKey(password, salt);
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    }
+    catch {
+        throw new Error('Wrong password or corrupted keystore.');
+    }
+}
+export async function deleteKeystore() {
+    try {
+        await unlink(keystorePath());
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}

package/dist/lib/telemetry.js

@@ -55,7 +55,7 @@ async function promptForConsent(anonymousId, filePath = TELEMETRY_CONFIG_PATH) {
     const prompter = createConsolePrompter();
     try {
         const accepted = await prompter.confirm({
-            message: 'Share anonymous CLI usage telemetry to improve Biomapper Link? Override anytime with AGENTLINK_TELEMETRY=on|off',
+            message: 'Share anonymous CLI usage telemetry to improve Humanode Agentlink? Override anytime with AGENTLINK_TELEMETRY=on|off',
             defaultValue: false,
         });
         const record = {

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const VERSION = pkg.version;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@techdigger/humanode-agentlink-cli",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Scaffold, link, and inspect Biomapper-ready agent projects.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -23,7 +23,7 @@
 		"cli": "tsx src/index.ts"
 	},
 	"dependencies": {
-		"@techdigger/humanode-agentlink": "^0.2.0",
+		"@techdigger/humanode-agentlink": "^0.1.0",
 		"posthog-node": "^5.21.2",
 		"viem": "^2.46.2"
 	},