hood-cli 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 nirholas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,471 @@
+# hood-cli
+
+**The command-line toolkit for [Robinhood Chain](https://docs.robinhood.com/chain/) (chain ID 4663).**
+
+Instant reads with zero config, guarded writes with an encrypted local wallet. Prices,
+portfolios, launches, swaps, transfers, transaction decoding — the `gh`/`vercel` of Robinhood
+Chain. Built on [`hoodchain`](https://github.com/nirholas/robinhood-chain-sdk) and
+[viem](https://viem.sh).
+
+Who it's for: anyone tracking Stock Tokens (tokenized equities on Robinhood Chain), watching
+NOXA/Odyssey memecoin launches, or scripting swaps and transfers from a terminal or CI job.
+Read commands (`price`, `stocks`, `coins`, `launches`, `tx`, `token`, `portfolio`, `watch`)
+work immediately with no wallet or API key. Write commands (`swap`, `transfer`,
+`deploy-token`) need a wallet and always stop for an explicit confirmation before signing.
+
+Docs + a live animated terminal demo (a REAL captured session, not invented output):
+**https://nirholas.github.io/hood-cli/** · full flag-by-flag command reference:
+**https://nirholas.github.io/hood-cli/commands.html** (generated straight from `hood
+<command> --help` — never hand-written, never drifts from the shipped binary).
+
+## Install
+
+```bash
+npm install -g hood-cli
+```
+
+This installs two equivalent binaries: `hood` and `hoodc`.
+
+Run without installing:
+
+```bash
+npx hood-cli price AAPL
+```
+
+From a checkout:
+
+```bash
+git clone https://github.com/nirholas/hood-cli.git
+cd hood-cli
+npm install
+npm run build
+node dist/cli.js price AAPL
+```
+
+Requires Node ≥ 20.
+
+## Quickstart
+
+```bash
+$ hood price AAPL
+◈ AAPL · Robinhood Chain mainnet
+Oracle    $315.50
+Updated   1d 18h ago
+DEX       no pool
+Premium   —
+Token     0xaF3D…93f9
+
+$ hood stocks --sort premium --dex --limit 6
+◈ Stock Tokens · mainnet · 6 shown · 6 priced
+SYMBOL    PRICE      DEX  PREMIUM     AGE  NAME                      ADDRESS
+────────────────────────────────────────────────────────────────────────────────
+CLSK     $12.86   $15.51  +20.58%  1d 17h  CleanSpark                0xcBB9…Cee3
+IONQ     $43.08   $49.44  +14.76%  1d 18h  IonQ                      0x5583…0EfE
+NBIS    $219.24  $248.41  +13.31%  1d 17h  Nebius Group               0x9D9c…7931
+
+$ hood portfolio 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52
+◈ Portfolio · 0x9701…3A52 · mainnet
+ETH      0.003784
+USDG     $0.0550
+Stocks   $0.00
+Total    $0.0550
+
+No Stock Token positions. Fund with `hood swap --sell USDG --buy <ticker>`.
+
+$ hood swap --sell USDG --buy WETH --amount 250
+◈ Swap quote · mainnet · add --execute to send
+Sell            250 USDG
+Buy             ~0.138501866807990729 WETH
+Min. received   0.137809357473950775 WETH (0.50% slippage)
+Rate            1 USDG ≈ 0.000554 WETH
+Route           direct pool
+```
+
+Every command supports `--json` for machine-readable output — pipe it into `jq` or a script.
+
+## Global options
+
+These apply to every command and must come before the subcommand name (`hood --json price AAPL`):
+
+| Flag | Description |
+| --- | --- |
+| `-v, --version` | print the CLI version |
+| `--json` | machine-readable JSON output instead of the human-formatted view |
+| `--network <net>` | `mainnet` (default) or `testnet` |
+| `--rpc <url>` | override the RPC endpoint for this invocation |
+| `--verbose` | show the raw underlying error cause on failure |
+| `--yes` | skip the interactive yes/no confirmation on writes (still requires `--execute`) |
+| `--acknowledge-eligibility` | affirm Stock Token acquisition eligibility (you are not a US/CA/UK/CH person) |
+| `--no-color` | disable ANSI colour in human output |
+| `-h, --help` | show help for the command |
+
+## Command reference
+
+| Command | Description |
+| --- | --- |
+| `price <symbol>` | Chainlink oracle price + DEX price + premium for a Stock Token |
+| `stocks` | The full Stock Token board with live Chainlink prices |
+| `coins` | Memecoin screener — newest or trending launches |
+| `launches` | Recent memecoin launches from NOXA and The Odyssey |
+| `portfolio <address>` | Multiplier-correct Stock Token positions + USD totals for an address |
+| `tx <hash>` | Decode a transaction: status, transfers, gas, method |
+| `token <address>` | Inspect a token: metadata, supply, multiplier, price |
+| `watch <addrOrToken>` | Live activity stream for an address or a token (ERC-20 transfers + native ETH) |
+| `swap` | Quote (default) or execute a Uniswap v3 swap between two tokens |
+| `transfer` | Send ETH or an ERC-20 token to an address |
+| `faucet` | Print testnet faucet instructions + current testnet balances |
+| `deploy-token` | Deploy a fixed-supply ERC-20 from a JSON config (direct-rail, no launchpad) |
+| `config` | Manage hood-cli settings (rpc, wallet, network) |
+
+Every argument below is a real, implemented flag — run `hood <command> --help` at any time to
+see it straight from the CLI.
+
+### `hood price <symbol>`
+
+Chainlink oracle price, DEX price, and the premium/discount between them for one Stock Token.
+
+| Flag | Description |
+| --- | --- |
+| `symbol` (arg) | ticker (`AAPL`) or token address |
+| `--watch` | live-updating view that repaints in place |
+| `--interval <ms>` | refresh interval for `--watch` (default `4000`) |
+| `--max-age <seconds>` | max acceptable Chainlink answer age |
+| `--no-dex` | skip the Uniswap price probe (oracle only) |
+
+```bash
+hood price AAPL
+hood price 0xaF3D... --no-dex
+hood price TSLA --watch --interval 2000
+```
+
+### `hood stocks`
+
+The full Stock Token board — every canonical, verified Stock Token with a live Chainlink feed.
+
+| Flag | Description |
+| --- | --- |
+| `--sort <key>` | `symbol` \| `price` \| `premium` (premium implies `--dex`); default `symbol` |
+| `--dex` | also probe Uniswap for DEX price + premium (slower) |
+| `--priced` | only show tokens with a live Chainlink feed |
+| `--limit <n>` | show at most `n` rows |
+
+```bash
+hood stocks
+hood stocks --sort premium --dex --limit 10
+hood stocks --priced --json
+```
+
+### `hood coins`
+
+Screener over the NOXA/Odyssey bonding-curve launchpads: newest launches, or ranked by trade
+activity.
+
+| Flag | Description |
+| --- | --- |
+| `--new` | newest launches (default) |
+| `--trending` | rank by bonding-curve trade activity |
+| `--lookback <blocks>` | blocks to scan (default `50000`) |
+| `--limit <n>` | rows to show (default `20`) |
+| `--names` | resolve token symbols on-chain |
+
+Mainnet only — the launchpads don't exist on testnet.
+
+```bash
+hood coins --names
+hood coins --trending --lookback 100000 --limit 10
+```
+
+### `hood launches`
+
+The raw launch feed for NOXA and The Odyssey, or a live stream of new ones.
+
+| Flag | Description |
+| --- | --- |
+| `--follow` | stream new launches live instead of a snapshot |
+| `--launchpad <name>` | `noxa` \| `odyssey` (default: both) |
+| `--lookback <blocks>` | blocks to scan for the snapshot (default `30000`) |
+| `--limit <n>` | max rows in the snapshot (default `25`) |
+| `--names` | resolve each token symbol on-chain |
+
+```bash
+hood launches --lookback 2000000 --limit 5 --names
+hood launches --follow --launchpad odyssey
+```
+
+### `hood portfolio <address>`
+
+Multiplier-correct Stock Token positions (share-equivalents, not raw balances) plus ETH,
+USDG, and a USD grand total.
+
+| Flag | Description |
+| --- | --- |
+| `address` (arg) | wallet address to inspect |
+| `--max-age <seconds>` | max acceptable Chainlink answer age |
+
+```bash
+hood portfolio 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52
+```
+
+### `hood tx <hash>`
+
+Decodes a transaction: status, from/to, value, method selector, gas, fee, block time, and
+every ERC-20 `Transfer` log inside it (symbols resolved for known Stock Tokens and read
+on-chain for anything else).
+
+```bash
+hood tx 0x870a3bee3070f10e3c4f34271cfde70fd5aa0dc2eade6f07d01ae6c9a00285bd
+```
+
+### `hood token <address>`
+
+Token metadata: name, decimals, total supply, holder count, the `uiMultiplier` for Stock
+Tokens, Chainlink oracle price (if it has a feed), and DEX price.
+
+| Flag | Description |
+| --- | --- |
+| `address` (arg) | token address or ticker |
+
+```bash
+hood token AAPL
+hood token 0xcBB9...
+```
+
+### `hood watch <addrOrToken>`
+
+Streams live activity until `Ctrl-C`. Without `--token`, a wallet address streams native ETH
+in/out plus every USDG transfer touching it (mainnet only — it needs the Stock Token
+registry). With `--token`, or when the argument isn't a valid address, it streams every
+transfer of that token.
+
+| Flag | Description |
+| --- | --- |
+| `addrOrToken` (arg) | wallet address, token address, or ticker to watch |
+| `--token` | treat the argument as a token (stream ALL transfers of it) |
+
+```bash
+hood watch 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52
+hood watch AAPL --token
+```
+
+### `hood swap`
+
+Quotes a Uniswap v3 swap by default; add `--execute` to sign and send it. Recognizes `USDG`,
+`WETH`/`ETH`, any Stock Token ticker, or a raw `0x` address for both `--sell` and `--buy`.
+
+| Flag | Description |
+| --- | --- |
+| `--sell <token>` | ticker or address to sell (e.g. `USDG`) — required |
+| `--buy <token>` | ticker or address to buy — required |
+| `--amount <amount>` | amount of `--sell` to spend, in whole tokens — required |
+| `--slippage <bps>` | slippage tolerance in basis points (default `50` = 0.5%) |
+| `--execute` | sign and send (default: quote only) |
+
+```bash
+hood swap --sell USDG --buy WETH --amount 250
+hood swap --sell USDG --buy AAPL --amount 500 --slippage 100 --execute
+```
+
+`--execute` prints a confirmation table and stops for an explicit `y`/`N` unless `--yes` is
+passed. It also checks the configured `maxSpendUsd` cap (see **Configuration** below) and
+Stock Token acquisition eligibility — a swap that mints/acquires a Stock Token for a
+non-affirmed operator fails with a guard error until you pass
+`--acknowledge-eligibility`.
+
+### `hood transfer`
+
+Sends native ETH or an ERC-20 token to an address.
+
+| Flag | Description |
+| --- | --- |
+| `--to <address>` | recipient address — required |
+| `--amount <amount>` | amount to send, in whole tokens — required |
+| `--token <token>` | ticker or address to send (default: native ETH) |
+
+```bash
+hood transfer --to 0x9701fb0aDe1E269c8f64Ec0C7b3cfADB31A13A52 --amount 0.01
+hood transfer --to 0x9701... --amount 100 --token USDG
+```
+
+Same confirmation gate and `maxSpendUsd` cap as `swap`.
+
+### `hood faucet`
+
+Prints the testnet faucet URL and instructions, plus your current testnet balances if a
+wallet is configured. Testnet-only (`--network testnet`); each claim (browser-only — it
+requires Cloudflare Turnstile + Google Sign-In and can't be automated) drips testnet ETH plus
+5 each of `TSLA`, `AMZN`, `PLTR`, `NFLX`, `AMD`.
+
+```bash
+hood faucet --network testnet
+```
+
+### `hood deploy-token`
+
+Deploys a fixed-supply ERC-20 (not a Stock Token, not launchpad-listed — a plain direct-rail
+token) from a JSON config.
+
+| Flag | Description |
+| --- | --- |
+| `--config <path>` | path to a JSON file: `{ name, symbol, decimals?, initialSupply }` — required |
+| `--execute` | sign and send (default: print the deploy plan only) |
+
+Config file example:
+
+```json
+{
+  "name": "My Token",
+  "symbol": "MTK",
+  "decimals": 18,
+  "initialSupply": 1000000
+}
+```
+
+```bash
+hood deploy-token --config ./mytoken.json
+hood deploy-token --config ./mytoken.json --execute
+```
+
+### `hood config`
+
+Manages the persistent CLI config at `~/.config/hood/config.json` (or `$HOOD_CONFIG_DIR`).
+
+| Subcommand | Description |
+| --- | --- |
+| `config set <key> [value]` | set a config value: `network`, `rpc`, `testnetRpc`, `alchemyKey`, `maxSpendUsd`, or `wallet` |
+| `config get <key>` | print one config value |
+| `config list` | print the full config (secrets masked) |
+
+```bash
+hood config set network testnet
+hood config set rpc https://your-rpc.example.com
+hood config set alchemyKey <your-alchemy-key>
+hood config set maxSpendUsd 500
+hood config set wallet
+hood config get walletAddress
+hood config list
+```
+
+`config set wallet` with no value generates a new private key (or, if
+`ROBINHOOD_CHAIN_IMPORT_KEY` is set, imports it), prompts twice for a password, and writes an
+AES-256-GCM keystore (scrypt KDF, Node's built-in `crypto` — the same primitive set as the
+Web3 Secret Storage spec) to `~/.config/hood/keystore.json`. The private key never touches the
+config file or plaintext disk.
+
+## Wallet & signing
+
+Every write command (`swap --execute`, `transfer`, `deploy-token --execute`, `config set
+wallet`) needs a signer. Precedence:
+
+1. `ROBINHOOD_CHAIN_PRIVATE_KEY` env var — a hex private key (with or without `0x` prefix).
+   Best for CI or power users; bypasses the keystore entirely.
+2. The encrypted keystore created by `hood config set wallet`, unlocked by a password prompt
+   (or the `HOOD_WALLET_PASSWORD` env var, so scripts never need an interactive TTY).
+
+No wallet is required for any read command (`price`, `stocks`, `coins`, `launches`, `tx`,
+`token`, `portfolio`, `watch`).
+
+## Configuration & environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `HOOD_CONFIG_DIR` | overrides the config/keystore directory (default `~/.config/hood`) |
+| `HOOD_WALLET_PASSWORD` | wallet keystore password, read non-interactively (for scripts/CI) |
+| `ROBINHOOD_CHAIN_PRIVATE_KEY` | sign with this private key directly, skipping the keystore |
+| `ROBINHOOD_CHAIN_IMPORT_KEY` | private key to import when running `hood config set wallet` (instead of generating a new one) |
+
+Persistent config keys (`hood config set <key> <value>`):
+
+| Key | Purpose |
+| --- | --- |
+| `network` | default network for every command: `mainnet` or `testnet` |
+| `rpc` | custom mainnet RPC URL |
+| `testnetRpc` | custom testnet RPC URL |
+| `alchemyKey` | Alchemy API key — builds `https://robinhood-mainnet.g.alchemy.com/v2/{key}` automatically |
+| `maxSpendUsd` | hard USD ceiling on a single `swap`/`transfer`; the write is refused if the estimated spend exceeds it (unpriceable tokens are never blocked, only warned about) |
+| `wallet` | special: runs the interactive wallet setup flow described above |
+
+Resolution order for RPC URL: `--rpc` flag → `alchemyKey` (mainnet) / `testnetRpc` → `rpc` →
+the SDK's public default.
+
+## Networks
+
+| Network | Chain ID | Notes |
+| --- | --- | --- |
+| `mainnet` (default) | 4663 | Stock Tokens, Chainlink feeds, NOXA/Odyssey launchpads, Uniswap v3 pools all live here |
+| `testnet` | 46630 | `TSLA`, `AMZN`, `PLTR`, `NFLX`, `AMD` faucet tokens; no launchpads, no Chainlink feeds |
+
+Pass `--network testnet` on any command, or set it once with `hood config set network
+testnet`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | success |
+| `1` | generic runtime failure |
+| `2` | bad usage / invalid arguments |
+| `3` | network / RPC unreachable or timed out |
+| `4` | a guard rail refused the action (eligibility, spend cap, unconfirmed prompt) |
+| `5` | requested resource not found (unknown symbol, missing transaction) |
+| `6` | wallet required but not configured, or wrong password |
+
+Every error also prints a human hint on how to fix it; add `--verbose` to see the raw
+underlying cause, or `--json` to get `{ error, hint, exitCode }` for scripting.
+
+## Safety notes
+
+- **Stock Token eligibility.** Stock Tokens are tokenized securities and may not be acquired
+  by US/CA/UK/CH persons. Any write that would acquire one refuses to run unless you pass
+  `--acknowledge-eligibility`, affirming you are not a person from a restricted jurisdiction.
+- **Confirmation gate.** `swap --execute`, `transfer`, and `deploy-token --execute` always
+  print a confirmation table and require an explicit `y` before signing, unless `--yes` is
+  passed. On a non-interactive stdin without `--yes`, the command fails closed rather than
+  hanging or silently proceeding.
+- **Spend cap.** Set `maxSpendUsd` once (`hood config set maxSpendUsd 500`) to have every swap
+  and transfer checked against it before signing.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsup → dist/cli.js (single self-contained ESM file)
+npm run typecheck
+npm test             # vitest run tests/unit — parsing, formatting, guard rails (offline)
+npm run e2e          # scripts/e2e.mjs — exercises the BUILT binary against live chain data
+```
+
+`npm run compile-erc20` regenerates `src/generated/erc20.ts` from `contracts/ERC20.sol`
+(the fixed-supply token `deploy-token` deploys) — only needed if you change the contract.
+
+### Docs site
+
+The `docs/` folder is a static site (GitHub Pages, deploy-from-branch, no build step on
+Pages itself) whose content is generated, never hand-written:
+
+```bash
+npm run capture        # drives the built binary against live mainnet, saves docs/session.json
+npm run docs:commands  # generates docs/commands-data.json from the CLI's own --help output
+npm run docs:build     # stitches both into docs/index.html + docs/commands.html
+npm run docs           # runs all three in order
+```
+
+`docs/index.template.html` and `docs/commands.template.html` are the editable sources;
+`docs/index.html` and `docs/commands.html` are the generated, real-data-inlined output that
+Pages actually serves — re-run `npm run docs` after any command change to keep them in sync.
+
+### Publishing
+
+```bash
+npm run build
+npm test
+npm pack               # verify the tarball installs clean: npm i -g ./hood-cli-*.tgz
+npm publish --access public
+```
+
+## License
+
+Apache-2.0 © 2026 nirholas. See [LICENSE](./LICENSE).
+
+---
+
+Built by [nirholas](https://x.com/nichxbt) · [three.ws](https://three.ws)