Nuelink CLI

Package: @nuelink/nuelink-cli Current version: 1.4.5 Command: nuelink-cli Requires: Node.js 18.17 or higher

The official command-line interface for the Nuelink Public API. Use it to manage brands, collections, automations, channels, media, and posts, read a brand’s schedule, and review published results, from local scripts, CI/CD pipelines, and terminal workflows.

The CLI is a third way into the same account. Anything the API can do, the CLI can do, with less ceremony:

nuelink-cli posts:create --brand-id BRAND_ID --collection-id COLLECTION_ID \
  --caption "Review this draft first." --publish-mode DRAFT --dry-run

Why use the CLI over raw HTTP

• Dry runs. Every API mutation accepts --dry-run, which performs local validation and prints the intended method, URL, JSON body, or upload metadata without sending an API request. It does not preview or suppress local auth/config changes, does not run server-side validation, and upload previews do not include multipart file bytes.
• Validation before the network. Bad enums, malformed dates, out-of-range pagination, and oversized files are caught locally, so you get a clear message instead of a 422.
• Readable by default, scriptable on demand. Lists print a table with a pagination summary. Add --json and stdout becomes a single JSON value you can pipe into jq.
• Credentials handled for you. Save a key once, or set an environment variable in CI, and stop writing Authorization headers.
• Retries and timeouts. GET requests retry with backoff. Everything has a timeout. Both are configurable.

Install

npm install -g @nuelink/nuelink-cli

Or run it without installing:

npx @nuelink/nuelink-cli --help

→ New to the CLI? Quick Start takes you from install to a verified draft in six steps.

Authentication

The CLI resolves credentials in this order, first match wins:

1. --api-key <apiKey> flag, for the current invocation only
2. NUELINK_API_KEY environment variable
3. Saved config file in your home directory

Use auth:login when you want to persist a key on a workstation. Prefer NUELINK_API_KEY in CI/CD, where a secret manager should own the value.

auth:status shows which of these sources the CLI resolved, without calling the API. auth:validate checks that key against the API.

The legacy --auth flag still works as a runtime-only alias for --api-key, but it’s deprecated.

Clear saved credentials

nuelink-cli auth:clear

Where the key is stored

OS	Path
macOS / Linux	$HOME/.nuelink-cli/config.json
Windows	%USERPROFILE%/.nuelink-cli/config.json

{
  "version": 1,
  "encryptedApiKey": "...",
  "iv": "...",
  "authTag": "..."
}

The config directory is created mode 0700 and the file is written atomically at mode 0600 where the OS supports POSIX permissions. The CLI refuses to follow a symlinked config path.

Saved-key encryption is obfuscation, not a secret manager

The encryption key is derived from constants shipped with the CLI. It can deter casual plaintext inspection, but anyone who copies the config file can reproduce the decryption key. Filesystem permissions are the effective protection. Prefer a secret manager that injects NUELINK_API_KEY, especially in automation.

Global options

Option	What it does
-a, --api-key <apiKey>	Use this key for the current invocation only
--auth <apiKey>	Deprecated alias for --api-key
--dry-run	For API mutation commands, validate and print the request without sending it; auth/config commands are unaffected
--json	Machine-readable JSON for both successes and failures
--quiet	Suppress API-request success banners; auth command messages are unchanged
-h, --help	Show help
-V, --version	Show version

Output and exit codes

Table mode (default) prints OK <METHOD> <PATH> followed by a formatted table and a pagination summary:

+------+-----------+-------------+------------+----------------------------+
| Id   | Title     | Description | Timezone   | Updated At                 |
+------+-----------+-------------+------------+----------------------------+
| 1001 | Example Brand | Example workspace | Europe/... | 2026-04-15T13:45:23.000000Z |
+------+-----------+-------------+------------+----------------------------+
Pagination: Page 1 of 1 | 25 per page | 2 total

JSON mode prints exactly one JSON value to stdout, so it pipes straight into jq. Successes keep the raw API response shape. Failures use a consistent envelope:

{
  "success": false,
  "error": {
    "code": "...",
    "message": "...",
    "httpStatus": null,
    "details": {}
  }
}

Exit code is non-zero on failure, so set -e scripts stop where you’d expect.

What gets caught before the network

The CLI rejects these locally, so you get a clear message instead of a round trip and a 422:

• Whitespace-only values in required fields
• Malformed JSON payloads, and JSON that isn’t an object
• Impossible or malformed dates, and scheduledAt outside YYYY-MM-DD HH:mm:ss
• Date ranges that end before they start, such as --created-to earlier than --created-from
• Invalid URLs, enum values, and boolean strings
• --page below 1, and --per-page outside 1–100
• Media files over the size limit, and unsupported extensions
• A posts:update with neither --publish-mode nor --queue-position, or a --scheduled-at that doesn’t match SCHEDULE

Where global options go

--json, --dry-run, --quiet, and --api-key are program-level options, so they work either before or after the command name:

nuelink-cli --dry-run posts:create --brand-id 13493 --collection-id 33273 --caption "Hi"
nuelink-cli posts:create --brand-id 13493 --collection-id 33273 --caption "Hi" --dry-run

Both are identical. Pick one and keep it consistent across a script.

Environment variables

Variable	Default	Notes
NUELINK_API_KEY	—	API key fallback when no --api-key flag is given
NUELINK_BASE_URL	https://app.nuelink.com/api/public/v1	Override for testing. Must be a valid absolute URL
NUELINK_TIMEOUT_MS	30000	Request timeout. Range 1–600000
NUELINK_GET_RETRIES	2	Retry count for GET requests only. Range 0–10
NUELINK_RETRY_BASE_MS	500	Backoff base. Non-negative, max 600000
NUELINK_RETRY_MAX_MS	2000	Backoff ceiling. Non-negative, max 600000
NUELINK_MAX_MEDIA_SIZE_BYTES	104857600 (100 MiB)	Local upload size guard. It can lower the limit, not raise it

NUELINK_TIMEOUT_MS=60000 nuelink-cli brands

How retries actually work

A request is retried only when all of these hold: the method is GET, the attempt count is under NUELINK_GET_RETRIES, and the status is 429 or 5xx.

The delay comes from the server when it offers one. If the response carries Retry-After, the CLI honors it, in either the seconds or the HTTP-date form. Otherwise it backs off exponentially from NUELINK_RETRY_BASE_MS, capped at NUELINK_RETRY_MAX_MS, with full jitter so parallel jobs sharing a key don’t retry in lockstep.

Mutations are never retried

POST, PATCH, and DELETE are never retried automatically, whatever the status, because the API doesn’t guarantee idempotency. If a create, update, or delete times out, list the resource before you run the command again.