The command line: tnb
A CLI (command-line interface) is a program you run by typing a command in a terminal instead of clicking in an app. Ours gives every workflow of the studio, your creations, tech packs, publishing and AI agents to anything that can run a command: an AI coding agent such as Claude Code, Codex or Cursor, a script, a cron, a CI job. One command each, JSON out, your local photos handled.
Install and sign in
npx @thenewblack/cli --help # nothing to install (Node 18+) npm install -g @thenewblack/cli # or keep it: the command is tnb tnb login # opens your profile's API tab, asks for the key once, keeps it export TNB_API_KEY=tnb_live_… # or: the environment wins — for a cron, a CI job, a container
The key comes from your profile, API tab. Without one, tnb workflows and every --help still work.
A folder of photos, without ever opening the site
Open your AI coding agent on a folder of product photos — the Code tab of Claude Desktop, Claude Code, Codex, Cursor — and say: “put all these garments on a model with The New Black”. The agent installs the CLI, asks for your key once, runs one command per photo, and the renders land in a sub-folder with readable names, a short report beside them. Tomorrow, “do the same with the new ones” — nothing to reinstall, nothing re-uploaded.
for f in ./products/*.jpg; do
tnb generate product_to_model --product_images "$f" \
--prompt "AI model wearing the product, studio light, neutral background" \
--ratio 4:5 --wait --out ./renders/
done
# → renders/green-dress-product_to_model.webp beside products/green-dress.jpgYou never see the terminal, the API or the parameters: you see sentences, and a folder that fills up.
One command per workflow, read live
The commands and their flags come from the platform's catalogue at the moment of the call — the same names as the workflows catalogue. Pictures are local files (uploaded once, remembered) or https urls.
tnb workflows # every workflow, with prices tnb generate virtual_try_on --help # the flags of one workflow: the live contract tnb generate virtual_try_on \ --product_images dress.jpg belt.jpg --model_image model.jpg \ --seg_camera slightly_above --ratio 4:5 --tier pro \ --wait --out ./renders/
{"generation_id":"3f1c9a6e-…","status":"succeeded","workflow":"virtual_try_on",
"url":"https://cloud.thenewblack.ai/…/result.webp","type":"image","file":"renders/dress-virtual_try_on.webp"}Without --wait the answer is the id, and tnb status <id> --wait --out ./renders/ picks it up later. Credits are debited at submission and refunded on failure.
Everything else of the API, one command each
tnb credits · account · ledger · brand-dna [read <id>] tnb media · elements · projects · upload <files…> tnb techpacks · techpack <id> · techpack pdf <id> · techpack rename <id> --name … tnb techpack add-section <id> --page <page_id> --kind bom · techpack write-section <id> <section_id> --data @file.json tnb techpack from-photos front.jpg --back back.jpg --sketch front --size-range XS-XL tnb moodboards · moodboard pdf <id> tnb shopify products · shopify publish --product <id> --media <media_id> tnb publish accounts · publish --account <connection_id> --placement <placement> --media <media_id> · post <id> tnb agents · agent send <id> "…" · agent thread <id> · agent stop <id> · agent schedule <id> "…" --kind single --date … --time … tnb files · file <id|path> --page 2 · file describe <id> --description "…"
tnb --help lists them; tnb <command> --help prints the flags. JSON on one line, --pretty to indent; errors are the platform's own { error: { code, message } } on stderr; exit code 0 done, 1 refused, 2 wrong command line.
CLI, MCP or API?
In a project of code, install the CLI. It is the door for anything that executes — an agent in a folder, a script, a cron, a CI job — whatever the editor or the AI. In a conversation, add the MCP connector. In your own backend, call the API. The CLI only ever calls that API: same account, same key, same credits. The Claude skill (npx skills add newblackai/claude-skill --skill thenewblack) teaches an agent all three.
Frequently asked questions
What is a CLI?
A command-line interface: a program you run from a terminal by typing a command, instead of clicking in an app. tnb is ours. Each command does one thing — generate with a workflow, read your credits, publish a creation — and answers with a line of JSON, so a person, a script or an AI coding agent can read the result and go on.
Why a CLI when there is an API?
The API is routes; a route has to be called from code you write. The CLI is the program already written: it uploads your local files, waits for the result, saves it under a readable name, and reads the catalogue for its own help. An AI agent gets to the first image in one command instead of ten steps of reading docs and writing a script — and the script never has to be rewritten next time.
Which agents and tools can use it?
Anything that can run npm: Claude Code, the Code tab of Claude Desktop, Codex, Cursor, a GitHub Action, a cron, a no-code tool with a shell step. Chat assistants without a terminal (Claude on the web, ChatGPT) use the MCP connector instead.
Does it need an account?
Yes. tnb login keeps your API key from your profile's API tab; TNB_API_KEY in the environment works for a server or a CI job. Every generation spends the credits of that account at the studio's prices. Without a key, tnb workflows and every --help still work.
Where do the files go?
Where you say. --out ./renders/ saves each result in that folder as <input name>-<workflow>.<ext>, next to your originals; --out file.webp names it. Results live 48 hours on our address, so the CLI saves them for you rather than handing you a link.
Does it follow new workflows?
Yes, without a new version. The commands and their flags are read from the platform's live catalogue at the moment of the call: a workflow added today is in tnb workflows and in tnb generate today.