Flatkey CLI: one credit balance for image, video, audio and text generation

What Flatkey CLI replaces, and who is meant to type the commands

The problem the README names is fragmentation. Image, video, speech, sound effects, music and text generation normally mean separate accounts, separate keys and separate billing, and the CLI's pitch is that one FLATKEY_API_KEY and one credit balance cover all of them. The second audience is explicit in the tagline: "Creative generation from the terminal for media teams and AI agents." That second half shapes the whole interface. JSON output, a documented stdout/stderr split, local file output and a dry-run flag are agent affordances, not conveniences for a designer. If you are generating a single hero image for a landing page, a browser tab is faster. If you are generating two hundred variations from a script and need to read the result programmatically, the shape of this tool starts to make sense.

The mechanism: a thin client over a hosted router, with local files as the interface

Nothing in the material suggests local model execution. The CLI is a client: it authenticates against a Flatkey account, sends a prompt plus parameters to a model identified by name, and writes the returned media to a path you specify with --output or -o. The model names in the examples are heterogeneous, which is the clearest evidence that a router sits in the middle. Image generation is shown with --model gpt-image-2, video with --model seedance2 and --model Seedance2.0-pro, speech with --model eleven_multilingual_v2 and a voice identifier, text with --model gpt-5.5. Those are not one vendor's family. The CLI also handles the awkward part of multimodal work: when you pass --image ./reference.png, or --first-frame and --last-frame for a transition, the README says the local file is uploaded through Flatkey temporary media first and then referenced by a signed URL. That is a real design decision with a real consequence. Your source images leave your machine. For product mockups that is fine; for unreleased client material it deserves a thought before you wire it into a pipeline. The video surface is the most parameterised: ratios of 16:9, 9:16, 4:3, 3:4, 21:9 and 1:1, and resolutions of 480p, 720p and 1080p. Audio splits into three subcommands with different flags, which is worth noting because audio generate takes voice tuning parameters (--voice-id, --stability, --similarity-boost, --style) while audio sfx takes --duration and audio music takes --music-length-ms. They are not one command with a mode switch, and a script that treats them as interchangeable will fail.

Getting it running: install, login, and the flags that matter

Installation is a global npm package. npm install -g @flatkey-ai/cli, or npx @flatkey-ai/cli help --ai if you want to inspect it without installing. The help flag --ai is unusual and worth trying before anything else, since it appears to be the intended entry point for an agent discovering the tool. Authentication defaults to an interactive browser flow: flatkey login opens an authorization page, waits for approval, and writes the API key plus account metadata into a local Flatkey config. If the terminal cannot open a browser, flatkey login --no-open prints the approval URL for you to open manually. There is also flatkey login --console-url https://console.flatkey.ai, described for staging or self-hosted console testing, which is a hint that the console endpoint is configurable rather than hardcoded. The non-interactive paths are an environment variable, export FLATKEY_API_KEY=<key>, or flatkey onboard --api-key <key> to persist a manually created key locally. Keys are created at console.flatkey.ai/keys. Once authenticated, flatkey auth status and flatkey status --json report the active state, and flatkey logout removes the saved key. The generation commands follow a consistent shape: flatkey image generate --prompt "..." --model gpt-image-2 -o cover.png, flatkey video generate --prompt "..." --model seedance2 --ratio 16:9 --resolution 720p -o launch.mp4, flatkey audio generate with a voice id and stability settings, flatkey text generate --prompt "..." --model gpt-5.5 -o headlines.txt. Two discovery commands, flatkey models --json and flatkey credits --json, are the ones I would run first on any new account, because they are the only documented way to learn what your key can reach and what balance remains.

JSON mode, progress animation, and the stdout contract

The README lists "Agent-friendly JSON mode with clean stdout" as a feature and separately notes that the terminal progress animation is "disabled in --json mode". Those two statements belong together. A progress animation writes escape sequences; if it ran during a JSON call, the output would not be parseable. The design intent is that --json produces machine-readable output on stdout and keeps everything else, including progress and errors, on stderr. That is the correct convention and it is stated rather than demonstrated. What the README does not give you is a single example of the JSON envelope: no sample key names, no schema, no error object shape. For a tool whose primary audience is described as AI agents, that is the largest documentation gap. An agent needs to know whether the response is an array of models or an object with a models field, and it needs to know how a failed generation is reported. You will have to discover that by running flatkey models --json against your own account.

The comparison table is the most opinionated thing in the repository

The README includes a product comparison against Higgsfield and Dreamina/Jimeng, and it is worth reading closely because it is where the project states its trade-offs, even if it does so in its own favour. The claims are relative: token pricing "at least ~20% lower than comparable retail routes", with image "~40% lower". No absolute prices appear anywhere in the supplied material, so the discount is unverifiable from the README alone and you should treat it as a starting point for your own arithmetic against flatkey credits --json. The queue claim is more concrete and more interesting: the README says that in the authors' testing, Dreamina/Jimeng video generation "can wait up to 5 hours during peak time". That is the strongest argument in the document, because it reframes the purchase. You are not buying cheaper pixels; you are buying iteration speed, and the value of that depends entirely on how many prompt-and-check cycles your workflow needs. The table's own admission about the alternatives is fair, too: Dreamina/Jimeng is described as stronger on ByteDance video models and cheaper in some local subscription workflows, and Higgsfield as the better polished creator suite. The stated split is honest. Use Flatkey when the job is repeated generation and automation; use a creator suite when you want its editing UI more than a programmable router.

Where it is the wrong tool, and what the README does not answer

The strongest case against Flatkey CLI is the one the README makes for its competitors without meaning to. If your work is a handful of images that you will retouch by hand, the CLI gives you a file and nothing else. There is no canvas, no layer model, no way to see a grid of variations and pick one. You would be paying for automation you do not use. The second limitation is structural: this is a hosted service with a credit balance, and every generation depends on a network round trip and on someone else's queue. The README's own complaint about peak-time waits applies to any hosted router, including this one, and the material contains no statement about Flatkey's own capacity or rate limits. Third, the CLI is a client for a proprietary backend. The MIT licence covers the JavaScript in this repository, not the models, not the gateway, and not the service. If Flatkey changes its pricing, retires a model name like seedance2, or shuts the router down, your installed CLI does not keep working. That is the normal arrangement for a hosted API client, but it should be stated plainly rather than discovered. Finally, the documentation is thin in specific places: no JSON schema, no error codes, no rate limits, no statement of what happens to uploaded reference images after generation, and no release notes in the supplied material despite a GitHub Actions publish workflow being present in the badges. The video example uses both seedance2 and Seedance2.0-pro as model strings, and it is not clear from the README whether model names are case-insensitive. Verify that before you hardcode one.

Maintenance and licence: an MIT client for a paid service

The repository is MIT licensed, which for a CLI means you can read it, fork it, vendor it into an internal tool and modify it. The licence does not extend to the generation service. Using the CLI still requires a Flatkey account, a key and credits, and those are governed by whatever terms the website sets, which the README does not reproduce. The last push recorded for the repository is 2026-08-31, and no releases were retrieved, so there is no versioned changelog to read in the supplied material. The badges do show an npm publish workflow, and the package is published as @flatkey-ai/cli, so updates arrive through npm rather than through tagged GitHub releases. Practically, that means your upgrade cost is npm install -g @flatkey-ai/cli and a re-read of the README, and your real risk is not the client code changing but the model names and pricing behind it. The README is also translated into Simplified Chinese and Japanese under docs/readme/, which is a small signal about the intended user base and a reminder that the primary docs are the English ones. There is no statement about a support channel, an SLA, or a deprecation policy for model identifiers, and I would not assume one exists. If your pipeline pins --model seedance2 in a script, that string is the thing most likely to break, not the CLI.

Editorial conclusion

Adopt Flatkey CLI if your workload is repeated, scripted generation across more than one modality and you want a single FLATKEY_API_KEY and one credit balance to cover it. Do not adopt it if you need an editing surface, if you cannot send prompts and reference images to a hosted service, or if you need to know per-call pricing before you commit, because the README quotes relative discounts rather than a published rate table. Verify three things first: run flatkey models --json and flatkey credits --json to see which models your account can actually reach and what a call costs, try flatkey image generate with --dry-run to confirm the flag behaves as the agent section implies, and check whether flatkey login works in your terminal or whether you need flatkey login --no-open.

Official sources

1. flatkey-ai/flatkey-cli on GitHub
2. Issues
3. License: MIT
4. Project website
5. README