Flisk CLI — generate and run your whole tech stack without the setup pain

Go from an empty folder to a running tech stack with one command. Built for agents.

_{ERP fixture scale run on a clean GitHub-hosted runner (4 vCPU, 15 GB RAM), snapshot from run 39160719471. The live status is in the ERP fixture scale E2E badge above.}

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Türkçe | Tiếng Việt | ไทย | Deutsch | Español | Français | Українська | Polski | Português (Brasil) | العربية | فارسی | Bahasa Indonesia | Italiano | Ελληνικά | മലയാളം

Website · Quickstart · Examples · Awesome Flisk · Demo · Report a bug

Stop letting AI hallucinate your local infrastructure.

LLMs are brilliant at writing application logic, but notoriously terrible at maintaining local infrastructure. Every time your AI rewrites a Dockerfile, misconfigures a Tiltfile, or breaks an nginx.conf, it wastes your developer focus and burns thousands of unnecessary API tokens.

Flisk CLI Core bridges the gap. You write the clean web application logic, and Flisk instantly autodetects your stack to generate, link, and orchestrate the local environment for you.

Build your app in one click

Fastest way (recommended): open the Flisk starter in a ready-to-use environment.

More build tools (7)

Deploy

More clouds and hosts (18)

Build app with your AI agent

More agents (7)

⚡ Zero-Config Local Stacks in About 14 Seconds

No vendor lock-in. No tedious plumbing. Run a single command to natively orchestrate 72 different integration tiers including:

• Runtimes & Frameworks: Bun, Node, Python, Go, Rust, React, Vue, Svelte, Elysia, Fastify, NestJS
• Databases & Tooling: Prisma, Drizzle, Atlas, Dbmate
• Messaging & Gateway: NATS, Traefik

🤖 Run your AI agents next to your services

Flisk is the local runtime for agent systems: the agent, its MCP tools, its database, its queue, behind one gateway, one command.

# Scaffold an agent, an MCP tools server, and a database in one stack
flisk resource bot --type agent --stack shop --yes
flisk resource tools-mcp --type mcp --stack shop --yes
flisk up shop

Agents get durable checkpoint volumes that survive flisk down, sticky session routing via x-session-id, graceful SIGTERM drain during hot reloads, a Docker health check on /health, and application-level readiness checks on /ready. See the AI agents guide and honest comparison with agent frameworks.

Flisk CLI — start services on your machine. It is not a deploy and not a Compose file: define each service in service.json, then run flisk up. No Kubernetes is needed on the machine.

Stability: 1.x local dev. Write service.json; Flisk generates the local runtime files. See what Flisk writes and how to check for drift. Core CLI is MIT and needs no key. Premium is optional.

Docker runs the containers. Tilt watches services and live-updates containers while you code. Flisk CLI writes the configuration Tilt uses. Production deployment stays with Helm, Argo CD, or Kustomize.

Important

Get Flisk from the flisk-sh/flisk repository, the @flisk-sh/flisk npm package, or the official website. Follow the installation links from these official sources. A similar repository name or copied README does not establish that a download is official.

Quick start · Why Flisk · Examples · Installation · FAQ · Documentation

If Flisk helps you run your local stack, a ⭐ on this repo helps other developers find it.

flisk ui opens an interactive terminal dashboard for inspecting running services. Move with ↑/↓ or j/k, search with /, and press 1–5 to jump between tabs. See docs/ui.md for every key binding.

Why Flisk CLI?

• One service.json per service. Flisk generates the Dockerfile, Traefik routing, and Tiltfile from it. You do not hand-write a docker-compose.yml or nginx.conf.
• Local stack without Kubernetes. Services run on Docker and Tilt on your machine. You do not need a local cluster such as kind or minikube.
• Hot reload while you code. Tilt live-updates the containers when files change.
• Generated files you can check. flisk records the generated files and reports drift, so local config stays in sync. See generated files and drift checks.

Capability	docker-compose	Local Kubernetes (kind, minikube)	Plain Tilt	Flisk CLI
Scaffold a new service in one command	No	No	No	Yes (flisk resource)
Hot reload on file change	Partial (compose watch)	Partial (extra tooling)	Yes	Yes
Health-checked startup order	Yes (depends_on: condition: service_healthy)	Yes	Manual configuration	Yes
Ingress routing and Postgres included	No	No	No	Yes (Traefik + Postgres)
Start only one stack of a large system	Partial (profiles)	Manual	Manual	Yes (flisk up <stack>)

See the detailed tool comparison for architectural tradeoffs, when each tool is the better choice, and migration workflows.

How Flisk works

1. Describe each service in a service.json next to its code.
2. Run flisk up <stack>. Flisk generates the local runtime files from those manifests: Dockerfiles, Traefik routing, and the Tiltfile.
3. Docker runs the containers and Tilt watches them. Edit code and the containers live-update. Use flisk ui to inspect running services, and flisk doctor or flisk config verify to check the environment and generated files.

Production deployment stays with your own tools (Helm, Argo CD, or Kustomize).

What you can do with Flisk

You want to	Flisk does	Command
Start a new project	Creates the project and first services	flisk project --yes
Add a service	Writes its service.json and generated files	flisk resource <name> --type backend --stack <stack> --yes
Start a whole stack	Starts Postgres, your services, and the routing, and prints the URLs	flisk up <stack>
Preview before starting	Shows which services and URLs would start, without containers	flisk up <stack> --dry-run
Inspect running services	Opens an interactive terminal dashboard	flisk ui
Check your machine	Reports Docker, Tilt, and port readiness	flisk doctor
Catch config drift	Compares generated files with what Flisk last wrote	flisk config verify
Keep Flisk current	Upgrades the CLI in place	flisk upgrade

Who uses Flisk

Teams that run flisk up on their own code (listed with their consent in ADOPTERS.md):

• Lekast, Flisk 1.3.178
• mfin.services, Flisk 1.3.140
• MakeOffer, Flisk 1.3.180
• Red Moon Digital, Flisk 1.3.81

Using Flisk too? Tell us or add a row to ADOPTERS.md.

If Flisk saves you time, a ⭐ on this repo helps other developers find it.

Quick start

There are two ways to get started. Both end with flisk up <stack>.

	Guided scaffolder	Core CLI (manual)
Best for	A first run: pick your services and get a ready project	Full control, or adding Flisk to an existing folder
Package	create-microservices	@flisk-sh/flisk (this repo)

Option A: guided scaffolder (recommended for beginners)

Prerequisites. Install these first. The scaffolder checks your machine while it creates the project and stops if something is missing:

• Node.js 22.12 or newer, and npm
• Docker, installed and running (Engine 25+, Compose 2.20.2+)
• Tilt
• Bun 1.2+

Run these commands from the directory where you want the new project folder to be created. The target directory must be new or empty; existing files are never overwritten.

npm install -g @flisk-sh/flisk
npm init create-microservices my-project
cd my-project
flisk up main

• npm install -g @flisk-sh/flisk installs the flisk command. Skip it if flisk --version already works.
• npm init create-microservices my-project asks how many services to create, then each service's name and type (backend, frontend, worker, or mcp).
• flisk up main starts the stack. main is the default stack name; if you pass --stack <name> to the scaffolder, use that name instead. The scaffolder prints the exact flisk up command when it finishes.

The scaffolder creates the project configuration and a skeleton for each service you selected, using Flisk CLI Core. It does not start any containers; flisk up does that.

To skip the prompts and get a default api (backend) and web (frontend):

npm init create-microservices my-project -- --yes

For service types, all options, and non-interactive usage, see the create-microservices README.

Note

Two similarly named packages exist. create-flisk is a landing-page app and does not scaffold projects. create-microservices is the project scaffolder used above.

Option B: core CLI (manual)

Use this to create the project and each resource yourself with flisk. Install the CLI first. Preview what a stack will start before any container runs:

flisk up shop --dry-run

Then try the full flow:

mkdir shop && cd shop
flisk project --yes
flisk resource orders-api --type backend --stack shop --yes
flisk up shop
curl http://api.shop.localhost/api/orders/health

flisk up prints the host ports it chose. It uses port 80 when it is free, so URLs carry no port. Otherwise it picks one from 8080-8180, and the URLs it prints include that port (on Linux and WSL2 a non-root user cannot check port 80, so the range is used there). Use the URL flisk up prints, or set TDK_HTTP_PORT. A resource named orders-api is served at /api/orders (a trailing -api is dropped); flisk up prints the exact URLs.

Scaffolding a backend and frontend, then listing the stack.

What Flisk writes for a frontend

You maintain service.json; Flisk generates the local runtime files. A frontend such as services/store/storefront-web has files like these after generation:

services/store/storefront-web/
├── service.json                         # your service definition
└── .autogenerated/                     # Flisk writes these files
    ├── nginx.autogenerated.conf        # serves the build and routes API requests
    ├── Dockerfile.app.autogenerated     # local app image
    ├── .env.frontend.autogenerated      # local frontend environment
    ├── vite.config.frontend.autogenerated.ts
    ├── tsconfig.autogenerated.json
    └── api-client.ts                    # generated API client

You do not need to write the nginx config, Dockerfile, or a docker-compose.yml for this local stack. flisk up uses Docker and Tilt to start it. The generated-files guide lists the other outputs and explains how regeneration and drift checks work.

If Helm, Compose, or your existing Tilt setup already gives you a working local environment, keep using it. Flisk CLI is for engineers managing several services who want a clear local service contract and one command to start the stack.

See how Flisk compares to alternative dev tools, how Flisk CLI works alongside Helm, the service schema, and the project configuration schema.

Terminal UI

Use flisk ui to inspect stacks and resources. Arrow keys or j/k move the selection; g/G or Home/End jump to the first/last item, and PageUp/PageDown move one visible page. / searches; navigation letters remain search text while searching. The selected row stays visible when the terminal is resized.

Update Flisk

Keep Flisk up to date to get the latest bug fixes:

flisk upgrade

flisk update is an alias for the same command. If you installed with npm, you can also run npm install -g @flisk-sh/flisk@latest. To pin a version or read what changed, see upgrading and version pinning.

Examples

Runnable examples show Flisk on real stacks. Start with the smallest one:

Example	What it shows
one-backend	One Bun/TypeScript backend with Postgres
one-backend-python	A Python backend in the same local stack
one-backend-helm	Working alongside Helm
byo	Bringing your own existing resources
byo-jobs	Bring-your-own jobs
tdk-example	A full multi-service stack

Use Flisk with your AI agent

The repository ships agent skills for common Flisk work, including flisk-doctor (environment checks) and flisk-troubleshoot (fixing flisk and Tilt errors), under .agents/skills. Agents working in this repo also follow AGENTS.md. Use these skills to let your agent check your setup and explain failures instead of guessing at Docker or Tilt configuration.

Installation

Install the CLI from npm (requires Node.js 22.12+) or use the prebuilt binary (no Node.js or Bun required):

npm install -g @flisk-sh/flisk
# or install the prebuilt binary
curl -fsSL https://flisk.sh/install.sh | sh

Public npm is the recommended default. To install through GitHub Packages instead, configure registry authentication as described in GitHub Packages installation.

flisk up shop --dry-run previews selected local services and URLs before starting containers. The default starter is Bun/TypeScript; Flisk's core role is running local containers through Docker + Tilt, not providing a Node.js application framework. See the one-backend example.

When not to use Flisk

• Your existing Compose or Tilt workflow already gives you a working local environment.
• Helm is your whole development workflow and you do not want local services on Docker.
• You do not want service.json manifests and generated local configuration.

Troubleshooting

Set TDK_DEBUG=1 before running flisk up --verbose to include Starlark debug logs in Tilt output.

Docs

• CLI command cheat sheet
• Mega cheat sheet: every command and flag
• Documentation index
• Pilot Flisk on a real repository
• Running AI agents in Flisk
• FAQ for agencies and multi-client teams
• Working alongside Helm
• Scope: local development, and what does not carry over to production
• Gradual adoption: adding Flisk to an existing repository
• Troubleshooting: flisk and Tilt error messages and their fixes
• Layout and ownership: services in several repositories
• Local data: reset, seed, snapshot
• Upgrading and version pinning
• Security: network calls, secrets and supply chain
• Pilot scorecard
• Bring-your-own resources
• Configuration and editor schemas
• Generated service files and drift checks
• Runnable one-backend example
• Runnable Python backend example
• Full multi-service example
• Features and license limits
• Tool comparison: docker-compose, Tilt, Skaffold, DevSpace, kind
• Honest comparison and known limits
• Public claims registry
• Show HN draft
• Architecture and repository map
• Scale fixture measurements and caveats
• Benchmark report: warm and cold start charts, history (updated on every change to main that affects start-up)
• How to run the start-time benchmark

History

Flisk development began on 21 April 2026. The archived, read-only flisk-sh/tdk repository records its first commit ("Initial commit: Flisk specs, generators, CLI, and standards") from that day. A separate tdk-cli history spanning 21 April to 18 September 2026 was imported into this repository as 306 filtered commits. Those commits are now ancestors of main; the import did not change the source tree.

This flisk repository was created on 19 September 2026, and the @flisk-sh/flisk npm package was first published on 21 September 2026. Those dates describe the current repository and package, not the start of Flisk development.

Requirements and support

For the local runtime, install Docker (Desktop, OrbStack, or Colima; Engine 25+, Compose 2.20.2+) and Tilt. Bun 1.2+ is used by the default generated services. Flisk selects host ports from bounded fallback ranges for HTTP, HTTPS, and Postgres; set TDK_HTTP_PORT, TDK_HTTPS_PORT, or TDK_POSTGRES_PORT to override them. Dev ports listen on 127.0.0.1 only, so other machines on your network cannot reach them. Set TDK_BIND_ADDRESS (for example 0.0.0.0, to test from a phone) to change that; flisk doctor warns when it is a wildcard address. Flisk supports macOS, Linux, and Windows through WSL2 Ubuntu; native Windows supports CLI inspection only. Run flisk doctor to check local readiness (supports --no-ping to skip service health checks and --ping-timeout <ms>). See WSL2 setup.

On native Windows, flisk --version, flisk doctor, and flisk up --dry-run are inspect-only commands. flisk up exits 1 with “Landscape startup needs Ubuntu on WSL2. Native Windows is inspect-only.”

License matrix

Capability	Free	Premium
flisk up, scaffold, Traefik, Postgres, Tilt live update, golden layers	yes	yes
Verdaccio, DDD scaffold, Sablier idle stop	no	key
Playwright, C4, AGENTS.md	free if generated in-repo	only if the implementation is downloaded with a key

Core stays free. Premium is a separate key for the extras above; no key required to run flisk up.

Ecosystem map: examples, articles, related tools, and notes live in awesome-tdk-framework. Star this repo (flisk) if the CLI is what you run; use the awesome list to browse the rest.

Share: X · Bluesky · Threads · Mastodon · Reddit · Hacker News · Facebook · LinkedIn · Telegram · WhatsApp · Email

FAQ

Do I need Kubernetes?

No. Flisk runs your services with Docker and Tilt on your machine. It does not need a local cluster such as kind or minikube, and it does not replace Helm, Compose, or your production deployment tools.

Do I need a license key?

No. Core CLI is MIT and needs no key to run flisk up. Premium extras are optional and use a separate key (see the license matrix).

Which platforms are supported?

macOS and Linux are supported directly. Windows is supported through WSL2 Ubuntu; native Windows supports CLI inspection only (flisk --version, flisk doctor, and flisk up --dry-run). See Requirements and support and WSL2 setup.

Does Flisk send my code anywhere?

Flisk runs the local stack on your machine. For network calls, secrets, and supply-chain details, see security: network calls, secrets and supply chain.

Can I keep using Compose, Helm, or my own Tilt setup?

Yes. If your existing setup already gives you a working local environment, keep using it. See working alongside Helm and gradual adoption for adding Flisk to an existing repository.

What should I do if I hit a bug?

Update first; a recent release may already fix it. Run flisk upgrade (also available as flisk update), or:

npm install -g @flisk-sh/flisk@latest

Then run flisk doctor and retry the same task. If the problem persists, open an issue with your Flisk version, operating system, steps to reproduce, and the error output. See upgrading and version pinning and troubleshooting.

Contributing and license

Contributions are welcome. Start with CONTRIBUTING.md and the contributor guide. For the project structure, see the architecture and repository map. To review pull requests, see Review a pull request. Report security issues using SECURITY.md.

Flisk is MIT-licensed; see LICENSE. The license boundary says which code is MIT and which is downloaded with a key.

Project governance: GOVERNANCE.md, MAINTAINERS.md, ADOPTERS.md.