CLI

The same account, the same credits, the same workspace — as subprocess commands. The CLI exists because a terminal agent often does better shelling out to a small command than carrying 301 tool definitions in its context.

Install

npm install -g hermoso
hermoso auth login          # opens a browser, stores the key locally
hermoso capabilities        # free — valid model ids and exact costs

The same package ships the stdio MCP server, so npx -y hermoso mcp and hermoso are one install.

Auth

hermoso auth login uses a loopback redirect, the same pattern as gh. The key is written to ~/.hermoso/config.json with the directory at 0700 and the file at 0600.

For CI, skip the browser and pass a key you created in the app:

hermoso auth login --token hmk_…
# or, without writing anything to disk:
HERMOSO_TOKEN=hmk_… hermoso capabilities

HERMOSO_API_BASE overrides the origin if you are running against your own server.

Commands

hermoso capabilities                # model ids + exact credit costs (free)
hermoso credits                     # balance (free)
hermoso brand                       # the saved brand profile
hermoso create --brand "Acme" --product "the best seller" --format image
hermoso generate image --prompt "…" --ref ./product.png --wait
hermoso generate video --prompt "…" --duration 8 --wait
hermoso competitors acme.com
hermoso research "Liquid Death's longest-running ads"
hermoso ads …                       # campaign management
hermoso jobs list | hermoso jobs get <id>
hermoso fetch <url>                 # pull media in from a link
hermoso mcp                         # run the stdio MCP server

Scripting

Every command takes --json and prints a machine-readable result, so a shell agent can parse rather than scrape. Renders are jobs: --wait polls to completion and prints the finished URL; without it you get a job id to poll yourself with hermoso jobs get.

URL=$(hermoso generate image --prompt "…" --wait --json | jq -r '.image')

What the CLI covers

The CLI mirrors the core tools — research, brand, create, generate, competitors, ads, jobs. It is deliberately not a command per tool: the full 301-tool surface is the MCP server, and hermoso mcp is in the same binary. Use the CLI for the common path and MCP for everything else.