@zoralabs/cli 0.3.1 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ A command-line tool for interacting with the [Zora](https://zora.co) protocol. E
 
 ## Install
 
-Requires **Node.js 24+**.
+Requires **Node.js 20+**.
 
 ```bash
 npm install -g @zoralabs/cli
@@ -15,6 +15,9 @@ npm install -g @zoralabs/cli
 ## Quick start
 
 ```bash
+# Guided first-time setup — wallet, API key, and deposit instructions
+zora setup
+
 # Browse trending coins
 zora explore
 
@@ -31,41 +34,39 @@ All commands support `--json` for machine-readable output. Commands with live da
 
 | Command         | Description                                               | Wallet required |
 | --------------- | --------------------------------------------------------- | --------------- |
+| `setup`         | Guided first-time setup (wallet + API key + deposit info) | —               |
 | `explore`       | Browse top, new, and highest volume coins                 | No              |
 | `get`           | Look up a coin by address or name                         | No              |
 | `price-history` | Display price history for a coin                          | No              |
 | `auth`          | Configure or check API key status                         | No              |
 | `profile`       | View creator or user profiles                             | No              |
-| `setup`         | Set up a wallet (generate or import private key)          | —               |
 | `buy`           | Buy a coin                                                | Yes             |
 | `sell`          | Sell a coin                                               | Yes             |
 | `balance`       | Show wallet balances (ETH, USDC, ZORA) and coin positions | Yes             |
-| `wallet`        | Show wallet address, storage location, or export key      | Yes             |
+| `wallet`        | Show wallet address, export key, or configure wallet      | Yes             |
 | `send`          | Send tokens to another address                            | Yes             |
 
 Run `zora --help` or `zora <command> --help` for detailed usage.
 
-## Wallet setup
+## Setup
 
-Commands that sign transactions require a wallet. Set one up with:
+`zora setup` walks through three steps: wallet configuration, API key (optional), and deposit instructions. It is re-runnable — existing configuration is detected and can be kept or overwritten.
 
 ```bash
-zora setup            # interactive — create or import a key
-zora setup --create   # generate a new key non-interactively
+zora setup            # interactive 3-step flow
+zora setup --create   # skip wallet prompt, generate a new key
+zora setup --yes      # non-interactive, accept all defaults
+zora setup --force    # overwrite existing wallet and API key
 ```
 
-The private key is stored locally at `~/.config/zora/wallet.json` with restricted permissions. Alternatively, set the `ZORA_PRIVATE_KEY` environment variable.
-
-## API key (optional)
+The private key is stored locally at `~/.config/zora/wallet.json` with restricted permissions. `ZORA_PRIVATE_KEY` and `ZORA_API_KEY` environment variables take precedence over saved config files.
 
-Read-only commands work without an API key but may be rate-limited. To get a key, create an account at [zora.co](https://zora.co) and generate one at [zora.co/settings/developer](https://zora.co/settings/developer), then:
+### Advanced
 
-```bash
-zora auth configure   # save the key
-zora auth status      # check current config
-```
+To configure wallet or API key individually (without running the full setup flow). All commands work without an API key but may be rate-limited:
 
-The `ZORA_API_KEY` environment variable takes precedence over the saved config.
+- `zora wallet configure` — create or import a wallet (`--create`, `--force`)
+- `zora auth configure` — save an API key; `zora auth status` — check current config
 
 ## Documentation
 

package/dist/index.js

@@ -285,6 +285,10 @@ var passwordOrFail = async (json, opts, nonInteractive) => {
   }
   return password(opts);
 };
+var passwordOrSkip = async (opts, nonInteractive) => {
+  if (nonInteractive) return "";
+  return password(opts);
+};
 
 // src/lib/analytics.ts
 import { PostHog } from "posthog-node";
@@ -437,7 +441,7 @@ var getClient = () => {
   return client;
 };
 var commonProperties = () => ({
-  cli_version: true ? "0.3.1" : "development",
+  cli_version: true ? "1.0.0" : "development",
   os: process.platform,
   arch: process.arch,
   node_version: process.version
@@ -500,7 +504,9 @@ var shutdownAnalytics = async () => {
 // src/commands/auth.ts
 var authCommand = new Command("auth").description(
   "Manage API key authentication.\nAPI key is optional \u2014 without one, requests are rate-limited.\nGet a key at https://zora.co/settings/developer"
-);
+).action(function() {
+  this.outputHelp();
+});
 authCommand.command("configure").description("Set your Zora API key").option("--yes", "Skip interactive prompt and execute directly").action(async function() {
   const json = getJson(this);
   const nonInteractive = getYes(this);
@@ -747,6 +753,13 @@ var formatAmountDisplay = (amount, decimals) => {
     maximumFractionDigits: 2
   }).format(Number(formatted));
 };
+function computeMarketCapChange24h(marketCap, marketCapDelta24h) {
+  if (marketCap === null || marketCapDelta24h === null || marketCap - marketCapDelta24h === 0)
+    return null;
+  return Number(
+    (marketCapDelta24h / (marketCap - marketCapDelta24h) * 100).toFixed(4)
+  );
+}
 var truncateAddress = (address) => `${address.slice(0, 6)}\u2026${address.slice(-4)}`;
 
 // src/lib/balance-format.ts
@@ -1166,11 +1179,10 @@ var formatBalanceJson = (balance, rank) => {
   const totalVolume = balance.coin?.totalVolume ? Number(balance.coin.totalVolume) : null;
   const priceUsdValue = priceUsd ? Number(priceUsd) : null;
   const usdValue = priceUsdValue !== null ? Number((parseRawBalance(balance.balance) * priceUsdValue).toFixed(6)) : null;
-  const marketCapChange24h = marketCap !== null && marketCapDelta24h !== null && marketCap - marketCapDelta24h !== 0 ? Number(
-    (marketCapDelta24h / (marketCap - marketCapDelta24h) * 100).toFixed(
-      4
-    )
-  ) : null;
+  const marketCapChange24h = computeMarketCapChange24h(
+    marketCap,
+    marketCapDelta24h
+  );
   return {
     rank,
     name: balance.coin?.name ?? null,
@@ -1193,13 +1205,9 @@ var formatBalanceJson = (balance, rank) => {
 function resolveContext(json) {
   const account = resolveAccount(json);
   const apiKey = getApiKey();
-  if (!apiKey) {
-    outputErrorAndExit(
-      json,
-      "Not authenticated. Run 'zora auth configure' to set your API key."
-    );
+  if (apiKey) {
+    setApiKey(apiKey);
   }
-  setApiKey(apiKey);
   return account;
 }
 function renderWallet(json, walletResult) {
@@ -1674,7 +1682,9 @@ var printQuote = (json, info) => {
  Buy \x1B[1m${info.coinName}\x1B[0m`);
   console.log(` ${info.coinType} \xB7 ${info.address}
 `);
-  console.log(`   Amount       ${spendFormatted} ${info.inputTokenSymbol}`);
+  console.log(
+    `   Amount       ${spendFormatted} ${info.inputTokenSymbol}${info.amountUsd ? ` (${info.amountUsd})` : ""}`
+  );
   console.log(`   You get      ~${coinsFormatted} ${info.coinSymbol}`);
   console.log(`   Slippage     ${info.slippagePct}%
 `);
@@ -1708,7 +1718,9 @@ var printTradeResult = (json, info) => {
  Bought \x1B[1m${info.coinName}\x1B[0m`);
   console.log(` ${info.coinType} \xB7 ${info.address}
 `);
-  console.log(`   Spent        ${spentFormatted} ${info.inputTokenSymbol}`);
+  console.log(
+    `   Spent        ${spentFormatted} ${info.inputTokenSymbol}${info.amountUsd ? ` (${info.amountUsd})` : ""}`
+  );
   console.log(`   Received     ${receivedFormatted} ${info.coinSymbol}`);
   console.log(`   Tx           ${info.txHash}
 `);
@@ -2150,8 +2162,9 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     amountOut,
     slippagePct
   };
+  const amountUsd = swapAmountUsd != null && inputToken.fixedPriceUsd == null ? `${amountMode === "usd" ? "" : "~"}${formatUsd(swapAmountUsd)}` : void 0;
   if (opts.quote) {
-    printQuote(json, quoteInfo);
+    printQuote(json, { ...quoteInfo, amountUsd });
     track("cli_buy", {
       action: "quote",
       coin_address: coinAddress,
@@ -2167,7 +2180,7 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     return;
   }
   if (!opts.yes) {
-    printQuote(false, quoteInfo);
+    printQuote(false, { ...quoteInfo, amountUsd });
     const ok = await confirm2({
       message: "Confirm?",
       default: false
@@ -2226,6 +2239,7 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     coinSymbol,
     coinType,
     address: coinAddress,
+    amountUsd,
     amountIn,
     inputTokenSymbol: inputToken.symbol,
     inputTokenDecimals: inputToken.decimals,
@@ -2548,6 +2562,47 @@ var ExploreView = ({
 
 // src/commands/explore.tsx
 import { jsx as jsx5 } from "react/jsx-runtime";
+var formatExploreCoinJson = (node) => {
+  const marketCap = node.marketCap ? Number(node.marketCap) : null;
+  const marketCapDelta24h = node.marketCapDelta24h ? Number(node.marketCapDelta24h) : null;
+  const marketCapChange24h = computeMarketCapChange24h(
+    marketCap,
+    marketCapDelta24h
+  );
+  const priceUsd = node.tokenPrice?.priceInUsdc ? Number(node.tokenPrice.priceInUsdc) : null;
+  const coinType = node.coinType ? COIN_TYPE_DISPLAY[node.coinType] ?? node.coinType : null;
+  const socials = node.creatorProfile?.socialAccounts;
+  const socialAccounts = socials ? {
+    instagram: socials.instagram ?? null,
+    tiktok: socials.tiktok ?? null,
+    twitter: socials.twitter ?? null,
+    farcaster: socials.farcaster ?? null
+  } : null;
+  return {
+    name: node.name ?? null,
+    description: node.description ?? null,
+    symbol: node.symbol ?? null,
+    coinType,
+    chainId: node.chainId ?? null,
+    address: node.address ?? null,
+    platformBlocked: node.platformBlocked ?? false,
+    totalSupply: node.totalSupply ?? null,
+    creatorAddress: node.creatorAddress ?? null,
+    creatorHandle: node.creatorProfile?.handle ?? null,
+    socialAccounts,
+    mediaContentMimeType: node.mediaContent?.mimeType ?? null,
+    mediaContentOriginalUri: node.mediaContent?.originalUri ?? null,
+    previewImage: node.mediaContent?.previewImage?.medium ?? null,
+    priceUsd,
+    marketCap,
+    marketCapDelta24h,
+    marketCapChange24h,
+    volume24h: node.volume24h ? Number(node.volume24h) : null,
+    totalVolume: node.totalVolume ? Number(node.totalVolume) : null,
+    uniqueHolders: node.uniqueHolders ?? null,
+    createdAt: node.createdAt ?? null
+  };
+};
 var QUERY_MAP = {
   mcap: {
     all: getMostValuableAll,
@@ -2659,7 +2714,10 @@ var exploreCommand = new Command4("explore").description("Browse top, new, and h
       outputErrorAndExit(json, `API error: ${msg}`);
     }
     const edges = response.data?.exploreList?.edges ?? [];
-    const coins = edges.map((e) => e.node);
+    const rawNodes = edges.map((e) => e.node);
+    const coins = rawNodes.map(
+      (node, i) => formatExploreCoinJson(node)
+    );
     const pageInfo = response.data?.exploreList?.pageInfo;
     outputJson({ coins, pageInfo: pageInfo ?? null });
     track("cli_explore", {
@@ -3243,7 +3301,7 @@ function printSellQuote(output, info) {
 `);
   console.log(`   Amount       ${info.soldFormatted} ${info.coinSymbol}`);
   console.log(
-    `   You get      ~${info.receivedFormatted} ${info.outputSymbol}`
+    `   You get      ~${info.receivedFormatted} ${info.outputSymbol}${info.receivedUsd ? ` (${info.receivedUsd})` : ""}`
   );
   console.log(`   Slippage     ${info.slippagePct}%
 `);
@@ -3283,7 +3341,7 @@ function printSellResult(output, info) {
 `);
   console.log(`   Sold         ${info.soldFormatted} ${info.coinSymbol}`);
   console.log(
-    `   Received     ${info.receivedSource === "quote" ? "~" : ""}${receivedFormatted} ${info.outputSymbol}`
+    `   Received     ${info.receivedSource === "quote" ? "~" : ""}${receivedFormatted} ${info.outputSymbol}${info.receivedUsd ? ` (${info.receivedUsd})` : ""}`
   );
   if (info.receivedSource === "quote") {
     console.log("   Note         based on quote");
@@ -3409,22 +3467,22 @@ var sellCommand = new Command7("sell").description("Sell a coin").argument(
       );
       return;
     }
-    const coinPriceUsd = await fetchTokenPriceUsd(coinAddress);
-    if (coinPriceUsd === null || coinPriceUsd <= 0) {
+    const coinPriceUsd2 = await fetchTokenPriceUsd(coinAddress);
+    if (coinPriceUsd2 === null || coinPriceUsd2 <= 0) {
       outputErrorAndExit(
         json,
         `Failed to fetch ${coinSymbol} price for USD conversion.`
       );
       return;
     }
-    const coinAmount = usdVal / coinPriceUsd;
+    const coinAmount = usdVal / coinPriceUsd2;
     amountIn = parseUnits2(coinAmount.toFixed(coinDecimals), coinDecimals);
     if (amountIn === 0n) {
       outputErrorAndExit(json, "Calculated amount is zero. USD too small.");
     }
     if (debug) {
       console.error(
-        `[debug] $${usdVal} USD = ${formatUnits5(amountIn, coinDecimals)} ${coinSymbol} (coin price: $${coinPriceUsd})`
+        `[debug] $${usdVal} USD = ${formatUnits5(amountIn, coinDecimals)} ${coinSymbol} (coin price: $${coinPriceUsd2})`
       );
     }
   } else if (amountMode === "amount") {
@@ -3472,18 +3530,19 @@ var sellCommand = new Command7("sell").description("Sell a coin").argument(
       }
     }
   }
+  const needsCoinPrice = amountMode !== "usd";
+  const needsOutputPrice = outputToken.fixedPriceUsd == null;
+  const [coinPriceUsd, outputPriceUsd] = await Promise.all([
+    needsCoinPrice ? fetchTokenPriceUsd(coinAddress) : Promise.resolve(null),
+    needsOutputPrice ? fetchTokenPriceUsd(outputToken.priceAddress) : Promise.resolve(null)
+  ]);
   let swapAmountUsd;
   if (amountMode === "usd") {
     swapAmountUsd = parsePercentageLikeValue(opts.usd);
-  } else {
-    const coinPriceUsd = await fetchTokenPriceUsd(coinAddress);
-    if (coinPriceUsd !== null && coinPriceUsd > 0) {
-      swapAmountUsd = Number(
-        (Number(formatUnits5(amountIn, coinDecimals)) * coinPriceUsd).toFixed(
-          2
-        )
-      );
-    }
+  } else if (coinPriceUsd !== null && coinPriceUsd > 0) {
+    swapAmountUsd = Number(
+      (Number(formatUnits5(amountIn, coinDecimals)) * coinPriceUsd).toFixed(2)
+    );
   }
   const tradeParameters = {
     sell: { type: "erc20", address: coinAddress },
@@ -3541,6 +3600,13 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     BigInt(quoteAmountOut),
     outputToken.decimals
   );
+  let receivedUsd;
+  if (outputPriceUsd != null) {
+    const outAmount = Number(
+      formatUnits5(BigInt(quoteAmountOut), outputToken.decimals)
+    );
+    receivedUsd = `~${formatUsd(outAmount * outputPriceUsd)}`;
+  }
   if (opts.quote) {
     printSellQuote(output, {
       coinName,
@@ -3554,7 +3620,8 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
       quoteAmountOut,
       outputSymbol: outputToken.symbol,
       outputDecimals: outputToken.decimals,
-      slippagePct
+      slippagePct,
+      receivedUsd
     });
     track("cli_sell", {
       action: "quote",
@@ -3584,7 +3651,8 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
       quoteAmountOut,
       outputSymbol: outputToken.symbol,
       outputDecimals: outputToken.decimals,
-      slippagePct
+      slippagePct,
+      receivedUsd
     });
     const ok = await confirm3({
       message: "Confirm?",
@@ -3641,6 +3709,12 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     } catch {
     }
   }
+  if (outputPriceUsd != null) {
+    const actualAmount = Number(
+      formatUnits5(receivedAmountOut, outputToken.decimals)
+    );
+    receivedUsd = `~${formatUsd(actualAmount * outputPriceUsd)}`;
+  }
   printSellResult(output, {
     coinName,
     coinSymbol,
@@ -3653,7 +3727,8 @@ ${err instanceof Error ? err.stack || err.message : String(err)}
     outputSymbol: outputToken.symbol,
     outputDecimals: outputToken.decimals,
     receivedSource,
-    txHash
+    txHash,
+    receivedUsd
   });
   track("cli_sell", {
     action: "trade",
@@ -3867,15 +3942,11 @@ var extractErrorMessage2 = (error) => {
   }
   return JSON.stringify(error);
 };
-var resolveApiKey = (json) => {
+var resolveApiKey = () => {
   const apiKey = getApiKey();
-  if (!apiKey) {
-    outputErrorAndExit(
-      json,
-      "Not authenticated. Run 'zora auth configure' to set your API key."
-    );
+  if (apiKey) {
+    setApiKey7(apiKey);
   }
-  setApiKey7(apiKey);
 };
 var formatPostJson = (post, rank) => ({
   rank,
@@ -3951,7 +4022,7 @@ var profileCommand = new Command8("profile").description("View profile activity
 ).action(async function(identifierArg) {
   const output = getOutputMode(this, "live");
   const json = output === "json";
-  resolveApiKey(json);
+  resolveApiKey();
   const { live, intervalSeconds } = getLiveConfig(this, output);
   let identifier = identifierArg;
   if (!identifier) {
@@ -4520,32 +4591,33 @@ var sendCommand = new Command9("send").description("Send coins or ETH to an addr
   }
 });
 
-// src/commands/setup.ts
+// src/commands/setup.tsx
 import { Command as Command10 } from "commander";
-import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
+import { Text as Text9, Box as Box9 } from "ink";
 
 // src/lib/strings.ts
-var DEPOSIT_INSTRUCTIONS = "Deposit ETH or USDC to this address on Base to start trading.\n\n  You can do this from:\n  - Coinbase \u2014 withdraw directly to Base\n  - Another wallet (MetaMask, Rainbow, etc.) \u2014 send on Base network\n  - Bridge from other chains \u2014 use https://superbridge.app/base";
+var DEPOSIT_SOURCES = "Deposit from:\n- Coinbase \u2014 withdraw directly to Base\n- Another wallet (MetaMask, Rainbow, etc.) \u2014 send on Base network\n- Bridge from other chains \u2014 use https://superbridge.app/base";
 var NO_WALLET_CONFIGURED = "No wallet configured.";
 var NO_WALLET_SUGGESTION = "Run 'zora setup' to create or import one.";
 var SAVE_ERROR_HINT = "Check that the directory exists and is writable.";
-var BACKUP_WARNING = "Back up this file \u2014 it's the only copy of your key.";
+var BACKUP_WARNING = "Back up this file \u2014 it's the only copy of your key. Zora is not responsible for any loss of funds.";
 
-// src/commands/setup.ts
+// src/lib/wallet-setup.ts
+import { generatePrivateKey, privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
 var isValidPrivateKey = (key) => /^(0x)?[0-9a-fA-F]{64}$/.test(key);
 var toAccount = (json, key, errorPrefix) => {
   try {
     return privateKeyToAccount4(normalizeKey(key));
   } catch {
-    outputErrorAndExit(
+    return outputErrorAndExit(
       json,
       `\u2717 ${errorPrefix} isn't a valid private key.`
     );
   }
 };
-var setupCommand = new Command10("setup").description("Set up your Zora wallet").option("--create", "Create a new wallet without prompting").option("--force", "Overwrite existing wallet without prompting").option("--yes", "Skip interactive prompt and execute directly").action(async function(options) {
-  const json = getJson(this);
-  const nonInteractive = getYes(this);
+var walletExistsWarning = (truncated) => `Wallet already configured: ${truncated}. Make sure your wallet is backed up \u2014 Zora is not responsible for any loss of funds.`;
+async function configureWallet(opts) {
+  const { json, nonInteractive, promptOverwrite } = opts;
   const envKey = process.env.ZORA_PRIVATE_KEY;
   if (envKey !== void 0) {
     if (!isValidPrivateKey(envKey)) {
@@ -4555,25 +4627,11 @@ var setupCommand = new Command10("setup").description("Set up your Zora wallet")
         "Fix it and run zora setup again."
       );
     }
-    const account = toAccount(json, envKey, "ZORA_PRIVATE_KEY");
-    outputData(json, {
-      json: { source: "env", address: account.address },
-      render: () => {
-        console.log("  Using wallet from ZORA_PRIVATE_KEY.\n");
-        console.log(`  Address: ${account.address}
-`);
-        console.log(`  ${DEPOSIT_INSTRUCTIONS}`);
-      }
-    });
-    track("cli_setup", {
-      action: "env_detected",
-      source: "env",
-      output_format: json ? "json" : "text"
-    });
-    return;
+    const account2 = toAccount(json, envKey, "ZORA_PRIVATE_KEY");
+    return { action: "env_detected", address: account2.address };
   }
   let existing;
-  if (!options.force) {
+  if (!opts.force) {
     try {
       existing = getPrivateKey();
     } catch (err) {
@@ -4585,20 +4643,33 @@ var setupCommand = new Command10("setup").description("Set up your Zora wallet")
     }
   }
   if (existing) {
-    const account = toAccount(json, existing, "Stored private key");
-    const truncated = truncateAddress(account.address);
-    console.log(`  Wallet already configured: ${truncated}
-`);
-    if (!options.force) {
-      outputErrorAndExit(
-        json,
-        "Wallet already exists.",
-        "Use --force to overwrite."
+    const account2 = toAccount(json, existing, "Stored private key");
+    const truncated = `${account2.address.slice(0, 6)}\u2026${account2.address.slice(-4)}`;
+    const warning = walletExistsWarning(truncated);
+    if (promptOverwrite) {
+      if (nonInteractive) {
+        return { action: "skipped", address: account2.address, warning };
+      }
+      const overwrite = await confirmOrDefault(
+        { message: "Overwrite wallet configuration?", default: false },
+        false
       );
+      if (!overwrite) {
+        return { action: "skipped", address: account2.address, warning };
+      }
+    } else {
+      if (!opts.force) {
+        outputErrorAndExit(
+          json,
+          `${warning}
+Wallet already exists.`,
+          "Use --force to overwrite."
+        );
+      }
     }
   }
   let choice;
-  if (options.create) {
+  if (opts.create) {
     choice = "create";
   } else {
     choice = await selectOrDefault(
@@ -4632,7 +4703,7 @@ var setupCommand = new Command10("setup").description("Set up your Zora wallet")
         );
       }
     }
-    const account = toAccount(json, importedKey, "Imported key");
+    const account2 = toAccount(json, importedKey, "Imported key");
     try {
       savePrivateKey(importedKey);
     } catch {
@@ -4642,64 +4713,201 @@ var setupCommand = new Command10("setup").description("Set up your Zora wallet")
         SAVE_ERROR_HINT
       );
     }
-    outputData(json, {
-      json: {
-        action: "imported",
-        address: account.address,
-        path: getWalletPath()
-      },
-      render: () => {
-        console.log("\n\u2713 Wallet imported\n");
-        console.log(`  Address:     ${account.address}`);
-        console.log(`  Private key: saved to ${getWalletPath()}
+    return {
+      action: "imported",
+      address: account2.address,
+      path: getWalletPath()
+    };
+  }
+  const privateKey = generatePrivateKey();
+  const account = toAccount(json, privateKey, "Generated key");
+  try {
+    savePrivateKey(privateKey);
+  } catch {
+    outputErrorAndExit(
+      json,
+      `\u2717 Couldn't save to ${getWalletPath()}.`,
+      SAVE_ERROR_HINT
+    );
+  }
+  return {
+    action: "created",
+    address: account.address,
+    path: getWalletPath()
+  };
+}
+
+// src/lib/ansi.ts
+var DIM = "\x1B[2m";
+var BOLD = "\x1B[1m";
+var YELLOW = "\x1B[33m";
+var RESET = "\x1B[0m";
+var useAnsi = () => process.stdout.isTTY && !process.env.NO_COLOR;
+
+// src/lib/warning-box.ts
+function warningBox(text) {
+  if (!useAnsi()) {
+    console.log(`\u26A0  ${text}
 `);
-        console.log(`  ${BACKUP_WARNING}
+    return;
+  }
+  console.log(`${YELLOW}\u26A0  ${text}${RESET}
+`);
+}
+
+// src/commands/setup.tsx
+import { jsx as jsx12, jsxs as jsxs9 } from "react/jsx-runtime";
+function stepLine(step, total, title) {
+  const cols = (process.stdout.columns || 80) - 4;
+  if (!useAnsi()) {
+    console.log(`
+[${step}/${total}] ${title}`);
+    console.log(`${"\u2500".repeat(Math.max(cols, 20))}
 `);
-        console.log(`  ${DEPOSIT_INSTRUCTIONS}`);
-      }
-    });
-    track("cli_setup", {
-      action: "imported",
-      source: "file",
-      output_format: json ? "json" : "text"
-    });
     return;
   }
-  if (choice === "create") {
-    const privateKey = generatePrivateKey();
-    const account = toAccount(json, privateKey, "Generated key");
-    try {
-      savePrivateKey(privateKey);
-    } catch {
-      outputErrorAndExit(
-        json,
-        `\u2717 Couldn't save to ${getWalletPath()}.`,
-        SAVE_ERROR_HINT
-      );
-    }
-    outputData(json, {
-      json: {
-        action: "created",
-        address: account.address,
-        path: getWalletPath()
-      },
-      render: () => {
-        console.log("\n\u2713 Wallet created\n");
-        console.log(`  Address:     ${account.address}`);
-        console.log(`  Private key: saved to ${getWalletPath()}
+  console.log(
+    `
+${BOLD}${DIM}[${step}/${total}]${RESET} ${BOLD}${title}${RESET}`
+  );
+  console.log(`${DIM}${"\u2500".repeat(Math.max(cols, 20))}${RESET}
 `);
-        console.log(`  ${BACKUP_WARNING}
+}
+var setupCommand = new Command10("setup").description("Guided first-time setup").option("--create", "Create a new wallet without prompting").option("--force", "Overwrite existing wallet without prompting").option("--yes", "Skip interactive prompt and execute directly").action(async function(options) {
+  const json = getJson(this);
+  const nonInteractive = getYes(this);
+  if (!json) stepLine(1, 3, "Set up wallet");
+  const walletResult = await configureWallet({
+    json,
+    nonInteractive,
+    create: options.create,
+    force: options.force,
+    promptOverwrite: true
+  });
+  if (!json) {
+    if (walletResult.action === "env_detected") {
+      console.log("Using wallet from ZORA_PRIVATE_KEY.");
+      console.log(`Address: ${walletResult.address}
 `);
-        console.log(`  ${DEPOSIT_INSTRUCTIONS}`);
+    } else if (walletResult.action === "skipped") {
+      warningBox(walletResult.warning);
+      console.log(`${DIM}Keeping existing wallet.${RESET}
+`);
+    } else {
+      const verb = walletResult.action === "created" ? "created" : "imported";
+      console.log(`\u2713 Wallet ${verb}`);
+      console.log(`Address:     ${walletResult.address}`);
+      console.log(`Private key: saved to ${walletResult.path}
+`);
+      warningBox(BACKUP_WARNING);
+    }
+  }
+  if (!json) stepLine(2, 3, "Set up API key (optional)");
+  let apiKeyStatus;
+  const envApiKey = getEnvApiKey();
+  if (envApiKey) {
+    apiKeyStatus = "env_override";
+    if (!json) {
+      console.log("API key is set via ZORA_API_KEY environment variable.\n");
+    }
+  } else {
+    const existingKey = getApiKey();
+    if (existingKey && !options.force) {
+      if (nonInteractive) {
+        apiKeyStatus = "already_set";
+        if (!json) {
+          console.log(
+            `API key already configured: ${maskKey(existingKey)}
+`
+          );
+        }
+      } else {
+        if (!json) console.log(`Current key: ${maskKey(existingKey)}`);
+        const overwrite = await confirmOrDefault(
+          { message: "Overwrite API key?", default: false },
+          false
+        );
+        if (!overwrite) {
+          apiKeyStatus = "already_set";
+          if (!json) console.log("");
+        } else {
+          apiKeyStatus = await promptAndSaveApiKey(json);
+        }
       }
-    });
-    track("cli_setup", {
-      action: "created",
-      source: "file",
-      output_format: json ? "json" : "text"
-    });
+    } else {
+      apiKeyStatus = await promptAndSaveApiKey(json, nonInteractive);
+    }
   }
+  if (!json) stepLine(3, 3, "Deposit");
+  if (!json) {
+    renderOnce(
+      /* @__PURE__ */ jsxs9(
+        Box9,
+        {
+          flexDirection: "column",
+          borderStyle: "single",
+          borderDimColor: true,
+          paddingX: 1,
+          paddingY: 1,
+          children: [
+            /* @__PURE__ */ jsxs9(Text9, { children: [
+              "Your address: ",
+              /* @__PURE__ */ jsx12(Text9, { bold: true, children: walletResult.address })
+            ] }),
+            /* @__PURE__ */ jsxs9(Text9, { children: [
+              "Deposit",
+              " ",
+              /* @__PURE__ */ jsx12(Text9, { bold: true, color: "blue", children: "ETH or USDC on Base" }),
+              " ",
+              "to start trading."
+            ] })
+          ]
+        }
+      )
+    );
+    console.log(`
+${DEPOSIT_SOURCES}
+`);
+  }
+  outputData(json, {
+    json: { wallet: walletResult, apiKey: apiKeyStatus },
+    render: () => {
+    }
+  });
+  track("cli_setup", {
+    wallet_action: walletResult.action,
+    api_key_status: apiKeyStatus,
+    output_format: json ? "json" : "text"
+  });
 });
+async function promptAndSaveApiKey(json, nonInteractive = false) {
+  if (!json && !nonInteractive) {
+    console.log(
+      "Optional. An API key unlocks higher rate limits for frequent trading."
+    );
+    console.log("Get your API key from: https://zora.co/settings/developer\n");
+  }
+  const apiKey = await passwordOrSkip(
+    { message: "Paste your API key (Enter to skip):" },
+    nonInteractive
+  );
+  const trimmed = apiKey.trim();
+  if (!trimmed) {
+    if (!json) console.log("Skipped API key configuration.\n");
+    return "skipped";
+  }
+  try {
+    saveApiKey(trimmed);
+    if (!json) console.log(`API key saved to ${getConfigPath()}
+`);
+    return "saved";
+  } catch (err) {
+    outputErrorAndExit(
+      json,
+      `Failed to save API key: ${fsErrorMessage(err, getConfigPath())}`
+    );
+  }
+}
 
 // src/commands/wallet.ts
 import { Command as Command11 } from "commander";
@@ -4715,9 +4923,9 @@ var resolvePrivateKey = () => {
   }
   return void 0;
 };
-var walletCommand = new Command11("wallet").description(
-  "Manage your Zora wallet"
-);
+var walletCommand = new Command11("wallet").description("Manage your Zora wallet").action(function() {
+  this.outputHelp();
+});
 walletCommand.command("info").description("Show wallet address and storage location").action(function() {
   const json = getJson(this);
   const resolved = resolvePrivateKey();
@@ -4773,21 +4981,69 @@ walletCommand.command("export").description("Print the raw private key to stdout
     output_format: json ? "json" : "text"
   });
 });
+walletCommand.command("configure").description("Create or import a wallet").option("--create", "Create a new wallet without prompting").option("--force", "Overwrite existing wallet without prompting").option("--yes", "Skip interactive prompt and execute directly").action(async function(options) {
+  const json = getJson(this);
+  const nonInteractive = getYes(this);
+  const result = await configureWallet({
+    json,
+    nonInteractive,
+    create: options.create,
+    force: options.force,
+    promptOverwrite: false
+  });
+  outputData(json, {
+    json: result,
+    render: () => {
+      if (result.action === "env_detected") {
+        console.log("  Using wallet from ZORA_PRIVATE_KEY.\n");
+        console.log(`  Address: ${result.address}
+`);
+        console.log(
+          `  Deposit ETH or USDC on Base to start trading.
+
+  ${DEPOSIT_SOURCES}`
+        );
+      } else if (result.action === "created" || result.action === "imported") {
+        const verb = result.action === "created" ? "created" : "imported";
+        console.log(`
+\u2713 Wallet ${verb}
+`);
+        console.log(`  Address:     ${result.address}`);
+        console.log(`  Private key: saved to ${result.path}
+`);
+        console.log(`  ${BACKUP_WARNING}
+`);
+        console.log(
+          `  Deposit ETH or USDC on Base to start trading.
+
+  ${DEPOSIT_SOURCES}`
+        );
+      } else if (result.action === "skipped") {
+        console.log(`  Wallet already configured: ${result.address}
+`);
+      }
+    }
+  });
+  track("cli_wallet_config", {
+    action: result.action,
+    output_format: json ? "json" : "text"
+  });
+});
 
 // src/components/StyledHelp.tsx
-import { Text as Text10, Box as Box10 } from "ink";
+import { Text as Text11, Box as Box11 } from "ink";
 
 // src/components/KeyValueTable.tsx
-import { Text as Text9, Box as Box9 } from "ink";
-import { jsx as jsx12, jsxs as jsxs9 } from "react/jsx-runtime";
+import { Text as Text10, Box as Box10 } from "ink";
+import { jsx as jsx13, jsxs as jsxs10 } from "react/jsx-runtime";
 function KeyValueTable({
   rows,
   labelWidth
 }) {
   const pad = labelWidth ?? Math.max(0, ...rows.map((r) => r.label.length)) + 2;
-  return /* @__PURE__ */ jsx12(Box9, { flexDirection: "column", children: rows.map((row, i) => /* @__PURE__ */ jsxs9(Text9, { children: [
-    /* @__PURE__ */ jsx12(Text9, { bold: true, children: row.label.padEnd(pad) }),
-    /* @__PURE__ */ jsx12(Text9, { dimColor: true, children: row.value })
+  return /* @__PURE__ */ jsx13(Box10, { flexDirection: "column", children: rows.map((row, i) => /* @__PURE__ */ jsxs10(Text10, { children: [
+    /* @__PURE__ */ jsx13(Text10, { bold: true, children: row.label.padEnd(pad) }),
+    /* @__PURE__ */ jsx13(Text10, { dimColor: true, children: row.value })
   ] }, i)) });
 }
 
@@ -4828,14 +5084,18 @@ function parseHelpSections(text) {
 }
 
 // src/components/StyledHelp.tsx
-import { jsx as jsx13, jsxs as jsxs10 } from "react/jsx-runtime";
+import { jsx as jsx14, jsxs as jsxs11 } from "react/jsx-runtime";
 function StyledHelp({
   sections,
   header
 }) {
   const descriptionColumnOffset = getDescriptionColumnOffset(sections);
-  return /* @__PURE__ */ jsxs10(Box10, { flexDirection: "column", gap: 1, children: [
+  return /* @__PURE__ */ jsxs11(Box11, { flexDirection: "column", gap: 1, children: [
     header,
+    /* @__PURE__ */ jsxs11(Box11, { paddingX: 1, children: [
+      /* @__PURE__ */ jsx14(Text11, { color: "yellow", children: "\u26A0 Beta:" }),
+      /* @__PURE__ */ jsx14(Text11, { children: " This CLI is in beta and should be used with caution." })
+    ] }),
     sections.map((section, i) => {
       const hasTwoColumns = TWO_COLUMN_REGEX.test(section.content);
       const rows = hasTwoColumns ? section.content.split("\n").map((line) => {
@@ -4847,8 +5107,8 @@ function StyledHelp({
           };
         return { label: "", value: line.trimStart() };
       }) : null;
-      return /* @__PURE__ */ jsxs10(
-        Box10,
+      return /* @__PURE__ */ jsxs11(
+        Box11,
         {
           flexDirection: "column",
           borderStyle: "single",
@@ -4856,8 +5116,8 @@ function StyledHelp({
           paddingX: 1,
           paddingY: 1,
           children: [
-            /* @__PURE__ */ jsx13(Text10, { bold: true, children: section.title }),
-            rows ? /* @__PURE__ */ jsx13(KeyValueTable, { rows, labelWidth: descriptionColumnOffset }) : /* @__PURE__ */ jsx13(Text10, { children: section.content })
+            /* @__PURE__ */ jsx14(Text11, { bold: true, children: section.title }),
+            rows ? /* @__PURE__ */ jsx14(KeyValueTable, { rows, labelWidth: descriptionColumnOffset }) : /* @__PURE__ */ jsx14(Text11, { children: section.content })
           ]
         },
         i
@@ -4867,10 +5127,10 @@ function StyledHelp({
 }
 
 // src/components/StyledHelpHeader.tsx
-import { Text as Text12, Box as Box12 } from "ink";
+import { Text as Text13, Box as Box13 } from "ink";
 
 // src/components/Zorb.tsx
-import { Text as Text11, Box as Box11 } from "ink";
+import { Text as Text12, Box as Box12 } from "ink";
 
 // src/lib/zorb-pixels.ts
 function supportsTruecolor() {
@@ -5015,7 +5275,7 @@ function generateZorbPixels(size) {
 }
 
 // src/components/Zorb.tsx
-import { jsx as jsx14, jsxs as jsxs11 } from "react/jsx-runtime";
+import { jsx as jsx15, jsxs as jsxs12 } from "react/jsx-runtime";
 var LOWER_HALF_BLOCK = "\u2584";
 var UPPER_HALF_BLOCK = "\u2580";
 function rgbString([r, g, b]) {
@@ -5038,19 +5298,19 @@ function Zorb({ size = 20 }) {
       const topIsBlack = isBlack(top);
       const bottomIsBlack = isBlack(bottom);
       if (topIsBlack && bottomIsBlack) {
-        cells.push(/* @__PURE__ */ jsx14(Text11, { children: " " }, x));
+        cells.push(/* @__PURE__ */ jsx15(Text12, { children: " " }, x));
       } else if (topIsBlack) {
         cells.push(
-          /* @__PURE__ */ jsx14(Text11, { color: rgbString(bottom), children: LOWER_HALF_BLOCK }, x)
+          /* @__PURE__ */ jsx15(Text12, { color: rgbString(bottom), children: LOWER_HALF_BLOCK }, x)
         );
       } else if (bottomIsBlack) {
         cells.push(
-          /* @__PURE__ */ jsx14(Text11, { color: rgbString(top), children: UPPER_HALF_BLOCK }, x)
+          /* @__PURE__ */ jsx15(Text12, { color: rgbString(top), children: UPPER_HALF_BLOCK }, x)
         );
       } else {
         cells.push(
-          /* @__PURE__ */ jsx14(
-            Text11,
+          /* @__PURE__ */ jsx15(
+            Text12,
             {
               backgroundColor: rgbString(top),
               color: rgbString(bottom),
@@ -5061,23 +5321,23 @@ function Zorb({ size = 20 }) {
         );
       }
     }
-    rows.push(/* @__PURE__ */ jsx14(Text11, { children: cells }, y));
+    rows.push(/* @__PURE__ */ jsx15(Text12, { children: cells }, y));
   }
-  return /* @__PURE__ */ jsxs11(Box11, { flexDirection: "column", children: [
-    /* @__PURE__ */ jsx14(Text11, { children: " " }),
+  return /* @__PURE__ */ jsxs12(Box12, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx15(Text12, { children: " " }),
     rows,
-    /* @__PURE__ */ jsx14(Text11, { children: " " })
+    /* @__PURE__ */ jsx15(Text12, { children: " " })
   ] });
 }
 
 // src/components/StyledHelpHeader.tsx
-import { jsx as jsx15, jsxs as jsxs12 } from "react/jsx-runtime";
+import { jsx as jsx16, jsxs as jsxs13 } from "react/jsx-runtime";
 function StyledHelpHeader({
   sections
 }) {
   const descriptionColumnOffset = getDescriptionColumnOffset(sections);
-  return /* @__PURE__ */ jsxs12(
-    Box12,
+  return /* @__PURE__ */ jsxs13(
+    Box13,
     {
       flexDirection: "row",
       borderStyle: "single",
@@ -5085,19 +5345,36 @@ function StyledHelpHeader({
       paddingX: 1,
       paddingY: 1,
       children: [
-        /* @__PURE__ */ jsx15(Box12, { flexShrink: 0, width: descriptionColumnOffset, children: /* @__PURE__ */ jsx15(Zorb, { size: 20 }) }),
-        /* @__PURE__ */ jsx15(Box12, { flexDirection: "column", flexGrow: 1, justifyContent: "center", children: /* @__PURE__ */ jsx15(Text12, { bold: true, children: "Zora CLI" }) })
+        /* @__PURE__ */ jsx16(Box13, { flexShrink: 0, width: descriptionColumnOffset, children: /* @__PURE__ */ jsx16(Zorb, { size: 20 }) }),
+        /* @__PURE__ */ jsxs13(Box13, { flexDirection: "column", flexGrow: 1, justifyContent: "center", children: [
+          /* @__PURE__ */ jsx16(Text13, { bold: true, children: /* @__PURE__ */ jsxs13(Text13, { backgroundColor: "#3fff00", color: "black", children: [
+            " ",
+            "Zora CLI",
+            " "
+          ] }) }),
+          /* @__PURE__ */ jsxs13(Text13, { children: [
+            /* @__PURE__ */ jsx16(Text13, { dimColor: true, children: "Trade what's trending. Run" }),
+            " ",
+            /* @__PURE__ */ jsxs13(Text13, { backgroundColor: "#3fff00", color: "black", children: [
+              " ",
+              "zora setup",
+              " "
+            ] }),
+            " ",
+            /* @__PURE__ */ jsx16(Text13, { dimColor: true, children: "to get started." })
+          ] })
+        ] })
       ]
     }
   );
 }
 
 // src/index.tsx
-import { jsx as jsx16 } from "react/jsx-runtime";
+import { jsx as jsx17 } from "react/jsx-runtime";
 if (process.env.ZORA_API_TARGET) {
   setApiBaseUrl(process.env.ZORA_API_TARGET);
 }
-var version = true ? "0.3.1" : JSON.parse(
+var version = true ? "1.0.0" : JSON.parse(
   readFileSync2(new URL("../package.json", import.meta.url), "utf-8")
 ).version;
 function styledHelpWriteOut(showHeader) {
@@ -5105,18 +5382,27 @@ function styledHelpWriteOut(showHeader) {
     if (supportsTruecolor()) {
       const sections = parseHelpSections(str);
       if (sections.length > 0) {
-        const header = showHeader ? /* @__PURE__ */ jsx16(StyledHelpHeader, { sections }) : void 0;
-        renderOnce(/* @__PURE__ */ jsx16(StyledHelp, { sections, header }));
+        const header = showHeader ? /* @__PURE__ */ jsx17(StyledHelpHeader, { sections }) : void 0;
+        renderOnce(/* @__PURE__ */ jsx17(StyledHelp, { sections, header }));
         return;
       }
     }
     process.stdout.write(str);
+    process.stdout.write(
+      "\n\x1B[33m\u26A0 Beta:\x1B[0m This CLI is in beta and should be used with caution.\n"
+    );
   };
 }
 var buildProgram = () => {
-  const program2 = new Command12().name("zora").description("A developer CLI for the Zora platform").version(version).option("--json", "Output as JSON (for scripts and automation)", false);
+  const program2 = new Command12().name("zora").description("Trade what's trending. Run `zora setup` to get started.").version(version).option("--json", "Output as JSON (for scripts and automation)", false);
   const helpWidth = (process.stdout.columns || 80) - 4;
-  program2.configureHelp({ helpWidth });
+  program2.configureHelp({
+    helpWidth,
+    commandDescription: (cmd) => {
+      if (!cmd.parent && supportsTruecolor()) return "";
+      return cmd.description();
+    }
+  });
   program2.configureOutput({ writeOut: styledHelpWriteOut(true) });
   program2.action(() => {
     program2.outputHelp();
@@ -5140,9 +5426,10 @@ var buildProgram = () => {
     }
   };
   applyToSubcommands(program2);
+  const argOptionalCommands = /* @__PURE__ */ new Set(["profile"]);
   program2.hook("preAction", (_thisCommand, actionCommand) => {
     const expected = actionCommand.registeredArguments.length;
-    if (expected > 0 && actionCommand.args.length === 0) {
+    if (expected > 0 && actionCommand.args.length === 0 && !argOptionalCommands.has(actionCommand.name())) {
       actionCommand.outputHelp();
       process.exit(1);
     }
@@ -5151,9 +5438,6 @@ var buildProgram = () => {
 };
 var program = buildProgram();
 if (!process.env.VITEST) {
-  console.warn(
-    "\x1B[33m\u26A0 Beta:\x1B[0m This CLI is in beta and should be used with caution."
-  );
   identify();
   try {
     await program.parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoralabs/cli",
-  "version": "0.3.1",
+  "version": "1.0.0",
   "description": "Zora CLI tool",
   "type": "module",
   "bin": {