@coinbase/cdp-cli 0.0.0 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coinbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# \@coinbase/cdp-cli
+
+Command-line interface for the [Coinbase Developer Platform](https://docs.cdp.coinbase.com/). Authenticate once, access every API from your terminal or AI agent.
+
+Zero runtime dependencies — just Node.js 22+.
+
+## Install
+
+```bash
+npm install -g @coinbase/cdp-cli
+```
+
+## Quick start
+
+```bash
+# 1. Set up your API key (get one at portal.cdp.coinbase.com)
+cdp env live --key-file ./cdp-api-key.json
+
+# 2. Make a request
+cdp evm accounts list
+
+# 3. Explore the API
+cdp api
+```
+
+## Commands
+
+### `cdp env` — Manage API keys
+
+Configure API keys once; all subsequent commands authenticate automatically.
+
+```bash
+cdp env                                           # list environments
+cdp env live --key-file ./cdp-api-key.json        # import key file from Portal
+cdp env live --key-id <id> --key-secret <secret>  # configure inline
+cdp env live --remove                             # remove an environment
+```
+
+Multiple API keys — prefix `live` to inherit its URL with a different key:
+
+```bash
+cdp env live-team-a --key-id <id> --key-secret <secret>  # inherits live URL, switches to live-team-a
+cdp env live                                              # switch back to live
+cdp evm accounts list -e live-team-a                      # one-off override without switching
+```
+
+#### Wallet secret
+
+Account write operations (create, sign, send) require a wallet secret. Generate one at [portal.cdp.coinbase.com/products/server-wallet/accounts](https://portal.cdp.coinbase.com/products/server-wallet/accounts), then add it to your environment:
+
+```bash
+cdp env live --wallet-secret <secret>
+# or, load from file
+cdp env live --wallet-secret-file ./cdp_wallet_secret.txt
+cdp evm accounts create name=my-wallet       # now works
+```
+
+The wallet secret is stored in your OS keyring alongside the API key. Manage it independently:
+
+```bash
+cdp env live --wallet-secret-file secret.txt  # add or update
+cdp env live --remove-wallet-secret           # remove (keeps API key)
+cdp env                                       # shows (wallet) indicator
+```
+
+For one-off use without persisting (e.g., testing with a key from a secrets manager):
+
+```bash
+CDP_WALLET_SECRET=$(cat secret.txt) cdp evm accounts create name=my-wallet
+```
+
+Custom environment names that don't start with `live` require `--url`:
+
+```bash
+cdp env custom --key-id <id> --key-secret <secret> --url https://api.cdp.coinbase.com/platform/v2
+```
+
+### `cdp <resource> <action>` — API operations
+
+Commands are generated from the CDP OpenAPI spec. Run `cdp api` to browse available endpoints.
+
+```bash
+cdp evm accounts list
+cdp evm accounts create name=my-wallet
+cdp evm faucet address=0x... network=base-sepolia token=eth
+cdp data evm token-balances base 0x...
+```
+
+Use `--template` to see the expected request shape before writing, and `--dry-run` to preview without sending:
+
+```bash
+cdp evm accounts create --template    # print request body template
+cdp evm accounts create --dry-run    # preview the assembled request
+```
+
+**Field syntax** (shared with `cdp api`):
+
+| Syntax | Meaning |
+|---|---|
+| `key=value` | String body field |
+| `key:=value` | Raw JSON body field |
+| `key==value` | Query parameter |
+| `a.b.c=value` | Nested body field |
+| `@file.json` | Body from file |
+| `-` | Body from stdin |
+| `Header:value` | Custom HTTP header |
+
+**Resource flags:**
+
+| Flag | Behavior |
+|---|---|
+| `--template` | Print request body template as JSON |
+| `--dry-run` | Print request without sending |
+| `--edit` | Open request body in `$EDITOR` |
+| `--jq <expr>` | Filter JSON response (requires [jq](https://jqlang.github.io/jq/)) |
+| `--paginate` | Auto-follow `nextPageToken` for full results |
+| `-e <env>` | Use a specific environment |
+
+### `cdp api` — Raw HTTP
+
+Lower-level access for endpoints or methods not covered by resource commands. Auth is handled automatically.
+
+```bash
+cdp api /evm/accounts
+cdp api -X POST /evm/accounts name=my-wallet
+cdp api -X POST /evm/accounts @body.json         # full body from file
+echo '{"name":"my-wallet"}' | cdp api -X POST /evm/accounts -
+cdp api /evm/accounts --jq '.accounts[].address'  # requires jq
+cdp api /evm/accounts --paginate                   # auto-follow nextPageToken
+cdp api /evm/accounts -v                           # show request + response headers
+```
+
+### `cdp api` — Browse the API
+
+Running `cdp api` with no arguments opens an interactive browser for the embedded OpenAPI spec.
+
+```bash
+cdp api                              # list all API groups
+cdp api /evm                         # endpoints in a group
+cdp api /evm/accounts --help         # full detail for one endpoint
+```
+
+### `cdp util` — Encoding and key utilities
+
+Helper commands for transaction encoding, ABI encoding, and key management.
+
+```bash
+cdp util tx-encode --to 0x... --value 1000000  # encode a transaction
+cdp util tx-decode 0x...                       # decode a raw transaction
+cdp util abi-encode 'transfer(address,uint256)' 0x... 1000  # ABI-encode calldata
+cdp util encrypt-key                           # encrypt a private key for import
+```
+
+### `cdp skills` — Workflow skills
+
+Manage reusable workflow skills (prompt templates) that extend the MCP server.
+
+```bash
+cdp skills list                # list available skills
+cdp skills add                 # install/update all bundled skills
+cdp skills add --dir <path>    # install to a specific directory
+cdp skills remove              # remove all installed skills
+```
+
+### `cdp history` — Request history
+
+View and manage a log of recent API requests made through the CLI.
+
+```bash
+cdp history        # show recent requests
+cdp history clear  # clear request history
+```
+
+## Claude Code / MCP
+
+`cdp mcp` starts an [MCP](https://modelcontextprotocol.io) server that gives Claude typed tool access to every CDP API endpoint. Tools are generated from the spec — new endpoints appear automatically when the CLI updates. Tool names mirror the nested subresource structure (e.g. `evm_accounts_create`, `evm_accounts_sign_message`).
+
+In addition to API tools, the MCP server exposes meta-tools for environment and workflow management:
+
+| Tool | Purpose |
+|---|---|
+| `cdp_set_env` | Switch the active API environment |
+| `cdp_env` | Show current environment and key info |
+| `cdp_help` | Get usage help for CLI commands |
+| `cdp_template` | Retrieve request body templates for endpoints |
+
+**If you installed the CLI globally:**
+
+```bash
+claude mcp add --scope user --transport stdio cdp -- cdp mcp
+```
+
+**MCP only** (no global install needed — runs via `npx`):
+
+```bash
+claude mcp add --scope user --transport stdio cdp -- npx -y @coinbase/cdp-cli mcp
+```
+
+> If you use both the CLI and MCP, install globally so they share the same version and spec.
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cdp": { "transport": "stdio", "command": "cdp", "args": ["mcp"] }
+  }
+}
+```
+
+**Auto-approve read operations** in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__cdp__cdp_env",
+      "mcp__cdp__cdp_help",
+      "mcp__cdp__cdp_template",
+      "mcp__cdp__cdp_*_list",
+      "mcp__cdp__cdp_*_get"
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables override config file values:
+
+| Variable | Purpose |
+|---|---|
+| `CDP_ENV` | Active environment name |
+| `CDP_KEY_ID` | API key ID |
+| `CDP_KEY_SECRET` | API key secret |
+| `CDP_URL` | Base URL override |
+| `CDP_WALLET_SECRET` | Wallet secret (alternative to `--wallet-secret`) |
+| `CDP_NO_HISTORY` | Set to `1` to disable request history |
+| `CDP_CONFIG_DIR` | Config directory (default: `~/.config/cdp`, `%APPDATA%\cdp` on Windows) |
+
+Keys and state are stored in `config.json` within the config directory.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)