@highlightxyz/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,30 +1,55 @@
-# @highlightxyz/cli
+# Highlight 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.
+Use `hl` to manage Highlight from a terminal, script, CI job, or agent. It
+covers collections, deployment, sales, gates, media, tokens, contracts, and
+chain configuration.
+
+The CLI is built on `@highlightxyz/sdk`. It calls the same API and follows the
+same validation rules as the SDK and REST API.
+
+[Read the CLI documentation](https://docs.highlight.xyz/cli/setup/).
 
 ## Install
 
+```sh
+npm install --global @highlightxyz/cli
+```
+
+Or use Bun:
+
 ```sh
 bun add --global @highlightxyz/cli
 ```
 
-Node.js 20 or later is supported.
+The CLI requires Node.js 20 or later.
+
+Verify the installation:
+
+```sh
+hl --version
+hl --help
+```
+
+You can run public commands before signing in:
+
+```sh
+hl chains list --testnet
+```
 
 ## Authenticate
 
-Create an API key in Highlight, then log in:
+Create an API key in Highlight, then save and verify it:
 
 ```sh
 hl auth login
+hl auth status
 ```
 
-For CI and agents, prefer an environment variable:
+For CI and agents, set the key in the process environment:
 
 ```sh
 export HIGHLIGHT_API_KEY="hl_live_..."
-hl auth status
+hl auth status --json
 ```
 
 Named profiles and custom API URLs are supported:
@@ -34,11 +59,11 @@ 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.
+On macOS and Linux, 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
+## Core commands
 
 ```sh
 hl collections list
@@ -47,75 +72,23 @@ 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
+hl media upload ./art.png
+hl media upload ./generative-code.zip --kind directory
+hl media get <media-id>
+hl media publish <media-id>
 
-```sh
 hl contracts list
 hl contracts get <contract-id>
 
@@ -129,30 +102,48 @@ 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
+Run group help for every option:
 
 ```sh
-hl media upload ./art.png
-hl media upload ./generative-code.zip --kind directory
-hl media get <media-id>
-hl media publish <media-id>
+hl collections --help
+hl sales --help
+hl media --help
 ```
 
-Uploads wait for processing by default. Use `--no-wait` for asynchronous jobs.
+Collection, sale, and gate writes accept JSON with `--input <file>`. Use
+`--input -` to read it from stdin.
+
+## Current boundaries
+
+`hl collections create` creates the base draft. Version `0.1.0` does not
+configure edition, series, or generative details, so complete those fields in
+the dashboard, SDK, or REST API before deployment.
+
+The CLI does not read or store wallet keys. When deployment or a live sale
+change needs an on-chain transaction, it prints the payload for a wallet to
+sign. It does not broadcast that transaction or submit its hash for tracking.
+
+Auction configuration is available through the generic sale commands. Bids,
+claims, standings, settlement, and earnings actions remain SDK or REST
+operations.
 
 ## Automation
 
-Pass `--json` anywhere in the command to receive stable machine-readable
-output:
+Pass `--json` anywhere in a command for 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.
+Successful JSON goes to stdout. Errors go to stderr. Commands return:
+
+- `0` on success
+- `1` for API, authentication, filesystem, timeout, or processing failures
+- `2` for invalid commands, options, arguments, or JSON input
 
-Run `hl --help`, `hl collections --help`, or `hl media --help` for all options.
+Pin the package version in production automation:
+
+```sh
+npm install --global @highlightxyz/cli@0.1.0
+```

package/lib/index.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@highlightxyz/cli",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "Official command-line interface for the Highlight API",
   keywords: [
     "cli",
@@ -18,13 +18,16 @@ var package_default = {
     url: "https://github.com/highlight-xyz/highlight-app.git",
     directory: "packages/cli"
   },
+  bin: {
+    hl: "./lib/index.js"
+  },
   files: [
     "lib",
     "README.md"
   ],
   type: "module",
-  bin: {
-    hl: "./lib/index.js"
+  publishConfig: {
+    access: "public"
   },
   scripts: {
     build: "bun build ./src/index.ts --outfile ./lib/index.js --target node --format esm",
@@ -45,9 +48,6 @@ var package_default = {
   },
   engines: {
     node: ">=20"
-  },
-  publishConfig: {
-    access: "public"
   }
 };
 
@@ -2096,6 +2096,62 @@ class Tx extends HeyApiClient {
   }
 }
 
+class Profile extends HeyApiClient {
+  get(options) {
+    return (options?.client ?? this.client).get({ url: "/user/profile", ...options });
+  }
+  update(parameters, options) {
+    const params = buildClientParams([parameters], [
+      {
+        args: [
+          { in: "body", key: "displayName" },
+          { in: "body", key: "bio" },
+          { in: "body", key: "website" },
+          { in: "body", key: "avatarMediaId" }
+        ]
+      }
+    ]);
+    return (options?.client ?? this.client).patch({
+      url: "/user/profile",
+      ...options,
+      ...params,
+      headers: {
+        "Content-Type": "application/json",
+        ...options?.headers,
+        ...params.headers
+      }
+    });
+  }
+  public(parameters, options) {
+    const params = buildClientParams([parameters], [{ args: [{ in: "path", key: "walletAddress" }] }]);
+    return (options?.client ?? this.client).get({
+      url: "/user/{walletAddress}/profile",
+      ...options,
+      ...params
+    });
+  }
+  tokens(parameters, options) {
+    const params = buildClientParams([parameters], [
+      {
+        args: [
+          { in: "path", key: "walletAddress" },
+          { in: "query", key: "page" },
+          { in: "query", key: "limit" },
+          { in: "query", key: "sort" },
+          { in: "query", key: "order" },
+          { in: "query", key: "collectionId" },
+          { in: "query", key: "search" }
+        ]
+      }
+    ]);
+    return (options?.client ?? this.client).get({
+      url: "/user/{walletAddress}/tokens",
+      ...options,
+      ...params
+    });
+  }
+}
+
 class Siwe extends HeyApiClient {
   nonce(options) {
     return (options?.client ?? this.client).post({ url: "/user/signin/siwe/nonce", ...options });
@@ -2239,6 +2295,10 @@ class HighlightClient extends HeyApiClient {
   get tx() {
     return this._tx ??= new Tx({ client: this.client });
   }
+  _profile;
+  get profile() {
+    return this._profile ??= new Profile({ client: this.client });
+  }
   _user;
   get user() {
     return this._user ??= new User({ client: this.client });
@@ -2286,7 +2346,7 @@ var resolveMediaUrl = (media, options) => {
 // src/config.ts
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
-var DEFAULT_API_URL = "https://api.highlightv2.xyz";
+var DEFAULT_API_URL = "https://api.highlight.xyz";
 var CONFIG_VERSION = 1;
 var defaultConfig = () => ({
   currentProfile: "default",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highlightxyz/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official command-line interface for the Highlight API",
   "keywords": [
     "cli",
@@ -16,13 +16,16 @@
     "url": "https://github.com/highlight-xyz/highlight-app.git",
     "directory": "packages/cli"
   },
+  "bin": {
+    "hl": "./lib/index.js"
+  },
   "files": [
     "lib",
     "README.md"
   ],
   "type": "module",
-  "bin": {
-    "hl": "./lib/index.js"
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "bun build ./src/index.ts --outfile ./lib/index.js --target node --format esm",
@@ -43,8 +46,5 @@
   },
   "engines": {
     "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }