# Flatkey's install hook pulls a runtime from a URL you can set, and its competitor table argues from first-hand numbers

> An MIT-licensed Node command line tool that routes image, video, audio and text generation to a single credit balance, aimed at agents with JSON output, dry runs and local file output. The install hook downloads a depth runtime from a configurable base URL, and the comparison section makes claims about two competitors that nothing in the repository supports.

**flatkey-ai/flatkey-cli** — Flatkey media generation CLI for images, videos, audio, text, credits, and model discovery.

- Repository: https://github.com/flatkey-ai/flatkey-cli
- Website: https://flatkey.ai/?utm_source=github&utm_medium=repo_homepage&utm_campaign=flatkey_cli
- Stars: 911 · Forks: 0
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/flatkey-ai-flatkey-cli

## The comparison table argues from first-hand numbers the repository cannot back

The most persuasive section of the README is the least verifiable. It states that in their testing, Dreamina and Jimeng video generation can wait up to five hours during peak time, and the table repeats it as observed waits of up to five hours for a single video generation test. The same row claims Flatkey token pricing is at least around twenty percent lower than comparable retail routes, and around forty percent lower for some modalities such as image, without naming a single competitor's price list or a date. Both claims are about other products, and nothing in an MIT-licensed CLI repository supports either. The rest of the table is qualitative and reasonable about what each tool is for.

## Installing globally runs a runtime download the quick start never mentions

The quick start is six lines:

```bash
npm install -g @flatkey-ai/cli
flatkey login

flatkey image generate --prompt "editorial cover, neon city at dawn" -o cover.png
flatkey video generate --prompt "cinematic product launch clip" --model seedance2 -o launch.mp4
flatkey audio generate --prompt "你好，这是 Flatkey 的配音测试" -o speech.mp3
flatkey models --json
flatkey credits --json
```

The first of those lines is the whole install, and it is not inert. The package manifest declares a postinstall script, node scripts/install-video-runtime.js, which runs on every install including a global one, and the README does not mention it anywhere in this block. It appears further down, under the video copy command, where the depth model is described as a platform runtime downloaded by the CLI. So a user who installs the tool only to generate an image still executes a network fetch at install time.

## The runtime comes from a base URL you can set, because no release channel exists yet

The download location is not fixed. Runtime distribution is configured through an environment variable, and the README explains the reason: the configuration stands until the Flatkey runtime release channel is published. That is an honest sentence and a real gap at the same time. Until that channel exists, the binary your machine executes after a global install is whatever the configured base URL serves, and nothing in the visible text describes a checksum, a signature or a pinned version for it. For an organization that blocks postinstall scripts by policy, that single hook is the reason this tool will be rejected, and the two supported workarounds are to run the CLI through npx with the help flag, or to review the script before installing.

## One model family is spelled three ways, and one example has a stray colon

Model identifiers are inconsistent across the examples in a way that will cost someone a failed command. The same Seedance family appears as seedance2 in the quick start, as Seedance2.0-pro in the reference-image example, and as seedance-2-5-pro in the multi-reference example. The image examples use a different naming style again, with gpt-image-2. The multi-reference block also contains a typo that breaks it if you paste it: a colon sits at the start of the line carrying the ratio flag, so the continuation is no longer a valid shell line.

```bash
flatkey video generate \
  --model seedance-2-5-pro \
  --prompt "保持人物、服装和镜头运动一致" \
  --image-url https://example.com/character.png \
  --video-url https://example.com/motion.mp4 \
: --ratio adaptive \
  -o result.mp4
```

The example prompts are in Chinese in both cases, which is consistent with the project's three README languages, though not with an English-only quick start.

## A local reference image is uploaded before the model sees it

The image upload command is described plainly: give it a local file and it returns a temporary signed URL. The video section then states the consequence for the workflow, that local reference images are uploaded through Flatkey temporary media first. So the file leaves the machine even though the tool is a local command line client and the generation is billed to your own balance, and the pointer that reaches the model is a URL hosted by the vendor. The URL is described as temporary without a stated lifetime. For a tool whose pitch is programmatic generation from a terminal, this is the fact worth internalising before anyone points it at a client asset directory, and it is buried two sections below the quick start.

## Four ways to hold the key, and one flag that redirects the authorization host

The authentication section is thorough, which is to say it offers four routes. The recommended one runs flatkey login, which opens a browser authorization page, waits for approval, and then saves the API key and account metadata into your local Flatkey config. A second route exports FLATKEY_API_KEY in the environment. A third stores a manually created key with an onboard subcommand that takes a key argument, and keys are created in a console page. A fourth removes the saved one with logout. The fifth detail is the one to look at twice, because login accepts a console URL flag, documented for staging or self-hosted console testing, which means the browser authorization flow can be pointed at a host other than the default. That is a legitimate feature and also a single flag away from sending an approval somewhere else.

## The published package is three directories, and the repository has no releases

The npm manifest lists bin, src and scripts as the entire contents of the published tarball. Everything else in the repository stays out of it: the test directory, the docs directory that holds the Simplified Chinese and Japanese readmes, the release directory, the release shell script, and a rust directory in a package whose primary language is JavaScript. The two translated readmes exist as files in the tree and are linked from the English one, and neither is available to anyone reading the package page. There are no GitHub releases at all, so the npm-publish workflow is the only distribution channel, the current version is 0.3.3, and the test command is the built-in Node test runner with no test files shipped alongside it. The last push is dated 2026-09-22.

## Conclusion

The command surface is well made for the audience it names. One binary across four media types, one key, one balance, JSON on stdout, a dry run before spending credits, and an explicit JSON marker when a capability has to degrade rather than fail quietly. The fallback marker in particular is the pattern more tools should copy. Two things deserve a pause before you install it. The postinstall hook downloads a native runtime on every install, the download location is set by an environment variable, and the project's own note says the runtime release channel does not exist yet, so you are running a binary fetched from a URL you can redirect. And the comparison section, which is the most persuasive part of the README, rests on figures the repository gives no way to check about competitors it does not otherwise test. Treat the pricing and queue claims as marketing and the command reference as documentation, because only one of the two is checkable.

## FAQ

### How do I install the Flatkey CLI?

With npm install -g @flatkey-ai/cli, or without installing anything by running npx @flatkey-ai/cli help --ai. The package requires Node 20 or newer, and the version can be checked with flatkey --version or flatkey -v.

### What does the Flatkey CLI run on install?

A postinstall script, node scripts/install-video-runtime.js, which installs the video runtime. Its download location is configured through FLATKEY_VIDEO_RUNTIME_BASE_URL until the Flatkey runtime release channel is published.

### How does the Flatkey CLI authenticate?

flatkey login opens a browser authorization page and then saves the API key and account metadata in your local config. You can also export FLATKEY_API_KEY, store a key with flatkey onboard --api-key, or remove the saved one with flatkey logout.

### Does a local reference image stay on my machine?

No. Local reference images are uploaded through Flatkey temporary media first, and flatkey image upload with a file argument returns a temporary signed URL for that purpose.

### What does flatkey video copy do?

It recreates a local video of 5 to 15 seconds using a generated Depth Anything V2 reference, with flags for frame ratio and depth resolution. If the upstream model cannot fetch video references, the command falls back to three depth keyframes and reports depth-keyframes-fallback in JSON output.

### Which video ratios and resolutions does the Flatkey CLI accept?

Ratios of 16:9, 9:16, 4:3, 3:4, 21:9, 1:1 and adaptive, and resolutions of 480p, 720p and 1080p.

## Sources

- [flatkey-ai/flatkey-cli on GitHub](https://github.com/flatkey-ai/flatkey-cli)
- [Issues](https://github.com/flatkey-ai/flatkey-cli/issues)
- [License: MIT](https://github.com/flatkey-ai/flatkey-cli/blob/main/LICENSE)
- [Project website](https://flatkey.ai/?utm_source=github&utm_medium=repo_homepage&utm_campaign=flatkey_cli)
- [README](https://github.com/flatkey-ai/flatkey-cli/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flatkey-ai-flatkey-cli