Install

Requires Node.js 22 or newer. These are the installation commands for the upcoming npm release on the next channel; publication is pending.

npm install -g @fluxnote.io/cli@next
fluxnote --version

# Without a global install, after publication
npx @fluxnote.io/cli@next --help

cd cli
npm ci
npm test
npm pack
npm install -g ./fluxnote.io-cli-0.1.0.tgz
fluxnote --help

Authenticate

Create a scoped key in Developers, then enter it at the hidden prompt. The CLI validates and saves it locally. The credential file is private but not encrypted.

fluxnote auth login
fluxnote whoami
fluxnote credits

# A separate local profile
fluxnote --profile local --api-url http://localhost:8080 auth login
fluxnote --profile local whoami

For CI, inject FLUXNOTE_API_KEY through your secret manager. Optional FLUXNOTE_PROFILE and FLUXNOTE_API_URL select the connection. Keys are never accepted as command-line flags. Saved keys stay tied to their API origin.

auth logout removes the saved key; it does not revoke the server key or unset environment variables.

Commands

Use fluxnote videos create --help for flags. Array flags use commas, boolean flags take true or false. Use --file request.json for complete request bodies or --file - for piped JSON; do not mix these with body flags.

Create a video

fluxnote options --kind templates
fluxnote voices

fluxnote videos create \
  --prompt "Three fascinating facts about the ocean." \
  --template faceless \
  --voice adrian \
  --language en \
  --target-duration 20 \
  --aspect-ratio 9:16 \
  --wait

Choose a voice from your catalog. The CLI shows a server estimate and asks for confirmation. For exact narration, replace --prompt with --script-file narration.txt. Do not include stage directions in narration. --prompt-file accepts a creative brief.

fluxnote videos download VIDEO_ID --output ocean.mp4

Downloads never overwrite an existing file unless you pass --overwrite.

Scripting

fluxnote videos create --file request.json --yes --wait --json
fluxnote videos get VIDEO_ID --json
fluxnote videos list --limit 20 --json
fluxnote videos list --all --json
fluxnote posts schedule --file post.json --yes --json

--json returns one JSON result on stdout, preserving API fields. No spinner or prompt is mixed into the output. Check the process exit code, resource status and any operation response_status; FluxNote does not add a synthetic success field. Writes require --yes in scripts or JSON mode.

Publishing uses your owned video and connected account IDs. Scheduled times require an explicit timezone. Caption jobs require --max-credits. Active series may generate recurring videos and spend credits.

Waiting and retries

Creation returns an ID immediately unless you use --wait. Waiting defaults to 15 minutes; set --timeout 1200 for 20 minutes. Polling backs off and respects API retry guidance. Scheduled posts stop waiting once scheduling is confirmed, not after publication.

fluxnote videos get VIDEO_ID --wait --timeout 1200
fluxnote operations get OPERATION_ID --wait
fluxnote posts get POST_ID --wait
fluxnote requests show RECEIPT_ID

Ctrl+C or a timeout stops local waiting, not the server job. Resume with the ID. Every write has a private local receipt; supported operations also get an idempotency key. After an uncertain submission, inspect the receipt and repeat identical input with its original --idempotency-key. Never replace the key blindly. Title updates and video deletion do not support replay keys; inspect the video before repeating those actions.

An operation receipt can be completed while its action failed: response_status >= 400 indicates failure. Waiting returns a nonzero exit code for this case. Reads retry transient failures; writes are never automatically retried.

Exit codes

0

Success

1

API or job failure

2

Authentication or permissions

3

Insufficient credits

4

Rate limit after retries

5

Invalid arguments or local configuration

6

Wait timeout; job may still be running

130

Interrupted or cancelled