@highlightxyz/cli 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @highlightxyz/cli
+
+Official command-line interface for the Highlight API. The `hl` binary is built
+on `@highlightxyz/sdk`, so CLI operations use the same generated public
+contract as TypeScript integrations.
+
+## Install
+
+```sh
+bun add --global @highlightxyz/cli
+```
+
+Node.js 20 or later is supported.
+
+## Authenticate
+
+Create an API key in Highlight, then log in:
+
+```sh
+hl auth login
+```
+
+For CI and agents, prefer an environment variable:
+
+```sh
+export HIGHLIGHT_API_KEY="hl_live_..."
+hl auth status
+```
+
+Named profiles and custom API URLs are supported:
+
+```sh
+hl auth login --profile staging --api-url http://localhost:8787
+hl collections list --profile staging
+```
+
+Saved keys live in `~/.config/highlight/config.json` with mode `0600`.
+`HIGHLIGHT_API_KEY`, `HIGHLIGHT_API_URL`, and `HIGHLIGHT_CONFIG_DIR` override
+saved configuration.
+
+## Collections
+
+```sh
+hl collections list
+hl collections get <highlight-id>
+hl collections create --input collection.json
+hl collections deploy <highlight-id> --wait
+hl collections deploy-status <highlight-id>
+hl collections deploy-cancel <highlight-id>
+```
+
+Creation input uses the SDK's `collection.create` shape:
+
+```json
+{
+  "name": "My Drop",
+  "description": "Created with the Highlight CLI",
+  "type": "OpenEdition",
+  "logoMediaId": "00000000-0000-0000-0000-000000000000",
+  "image": "https://assets.example/art.png",
+  "contract": {
+    "chainId": 84532,
+    "name": "My Drop",
+    "symbol": "DROP",
+    "standard": "ERC721"
+  }
+}
+```
+
+Use `--input -` to read JSON from stdin.
+
+## Sales
+
+```sh
+hl sales list <highlight-id>
+hl sales create <highlight-id> --input sale.json
+hl sales update <highlight-id> <sale-id> --input sale-update.json
+hl sales delete <highlight-id> <sale-id>
+```
+
+Sale input uses the SDK's `collection.addSale` body shape:
+
+```json
+{
+  "type": "FIXED_PRICE",
+  "accessMode": "PUBLIC",
+  "startAt": "2026-01-01T00:00:00.000Z",
+  "price": "0.01",
+  "currency": "ETH",
+  "maxPerTransaction": 5,
+  "maxPerWallet": 10,
+  "maxTotal": 100,
+  "paymentRecipient": "0x0000000000000000000000000000000000000001"
+}
+```
+
+The API enforces the collection functionality matrices. Unsupported
+combinations, such as gated ranked auctions, return the canonical domain error.
+Live public sale changes can return a transaction payload that requires a
+wallet signature.
+
+## Gates
+
+```sh
+hl gates list
+hl gates get <gate-id>
+hl gates create --input gate.json
+hl gates update <gate-id> --input gate-update.json
+hl gates delete <gate-id>
+```
+
+Gate JSON uses the SDK `gate.create` or `gate.update` body shape and supports
+allowlists, token ownership, specific tokens, token attributes, currency
+balances, and Farcaster follows.
+
+## Contracts, tokens, and chains
+
+```sh
+hl contracts list
+hl contracts get <contract-id>
+
+hl tokens list <highlight-id>
+hl tokens get <highlight-id> <token-id>
+hl tokens owners <highlight-id> <token-id>
+hl tokens facets <highlight-id>
+hl tokens redrive <highlight-id>
+
+hl chains list --testnet
+hl chains system-contract 84532 MintManager
+```
+
+Token reads and chain configuration are public and do not require credentials.
+Contract queries and token reveal redrives require authentication.
+
+## Media
+
+```sh
+hl media upload ./art.png
+hl media upload ./generative-code.zip --kind directory
+hl media get <media-id>
+hl media publish <media-id>
+```
+
+Uploads wait for processing by default. Use `--no-wait` for asynchronous jobs.
+
+## Automation
+
+Pass `--json` anywhere in the command to receive stable machine-readable
+output:
+
+```sh
+hl collections list --json
+hl media upload ./art.png --json
+```
+
+Errors are written to stderr and commands return non-zero exit codes.
+
+Run `hl --help`, `hl collections --help`, or `hl media --help` for all options.