Use in an Agent

Let Claude Code, OpenClaw and other agents make images and videos through the tufty CLI.

tufty is built for agents: stdout carries exactly one JSON envelope, progress and hints go to stderr, and exit codes separate success, runtime errors and usage errors. Any agent that can run a shell command can use every tufty.ai studio tool.

Quick-start prompt

Send this to your agent:

Install the tufty CLI with npm install -g @tufty/cli, run tufty -h and tufty tools list to learn the available tools, then remind me to run tufty login.

From there, an agent typically:

reads a tool's inputs, options and prices with tufty <tool> -h or tufty tools describe <id>;
adds --dry-run first to estimate credits, and runs for real once you confirm;
reads result.outputs[].url from stdout, or saves the files locally with --save <dir>.

Signing in

Commands run by an agent usually have no interactive terminal. In that case the CLI does not start a login; it returns no_api_key straight away. Two ways to fix that:

Run tufty login once in your own terminal (recommended). The key is saved to ~/.tufty/config.json, and agents on the same machine can use it from then on.
Set the TUFTY_API_KEY environment variable, for CI, containers or remote sandboxes. Get a key under Account settings → API keys; it starts with sk-.

See Authentication.

Reading the result

{
  "ok": true,
  "result": {
    "tool": "pet-dressup",
    "runId": "3f6c2a1e-8b4d-4e7a-9c55-0d2b7e1f4a90",
    "status": "completed",
    "outputs": [
      { "type": "image", "url": "https://static.tufty.ai/.../result.png" }
    ]
  }
}

Check ok first: when true, read result; when false, read code, message and details.
Parse stdout only. Stderr holds progress, the credit estimate and hints — don't mix the two.
When you only need the files, add --format url and stdout lists one output URL per line.

Two errors an agent must handle

code	The agent should
`insufficient_balance`	Tell the user plainly that they are out of credits (`details.required` is what this step needs) and give them the top-up link https://tufty.ai/dashboard/settings?tab=credits. Don't retry on its own.
`unauthorized` / `no_api_key`	Tell the user to get an API key at https://tufty.ai/dashboard/settings?tab=api-keys, save it with `tufty auth set <key>` (or run `tufty login`), then carry on.

All other codes are listed under Error codes.

Long-running jobs

Videos usually take a few minutes. By default the CLI waits until the run finishes (up to --timeout seconds, 900 by default). If your agent limits how long one command may run, use --no-wait to get the runId first, then fetch the result with tufty status <runId> --wait:

tufty image-to-video --still ./corgi-sweater.png --no-wait
tufty status 9b1d4c7e-2f3a-4d8b-a6e5-7c0f1e2d3b4a --wait

See Async runs and status.

Using skills

Agents that support skills, such as OpenClaw, can install the tufty tool skills, which already spell out triggers, commands and error handling. See Skills.

Troubleshooting

command not found: tufty: npm's global bin directory isn't on the agent's PATH. Use npx @tufty/cli <command> instead.
manifest_unavailable: the CLI couldn't reach https://tufty.ai to load the tool manifest. Check the network or proxy.
cli_version_too_low: upgrade with npm install -g @tufty/cli@latest.