Getting started & command reference

The Flicker CLI

One static binary drives your whole stack — deploys, environment and secrets, databases, copy-on-write branches, Tickets, and project memory. The same commands run on your laptop and in CI, every grammar is flicker <noun> <verb> <name>, and every create or deploy is idempotent and exits non-zero on failure — so a pipeline never leaks a preview database, hides a broken step, or loses the current task contract.

This page is the quick tour. For the full developer guide — getting started, the secrets model, deploys, dependencies, volumes, and an exhaustive command reference — see the documentation .

Install

The flicker CLI is a single static binary — no runtime, no dependencies. Drop it on your PATH and verify it:

$ curl -fsSL https://flickercloud.com/install.sh | sh $ flicker help

The installer detects your platform. Direct downloads: macOS (Apple silicon, Intel), Linux (x86-64, arm64), and Windows. A Homebrew tap is planned.

Authenticate

Mint an API token in the web UI under Settings → API Keys (the plaintext is shown once). The token authenticates every call and pins which organization you act as.

$ flicker auth login flk_live_xxx # stored in ~/.config/flicker/config.toml (0600)

In CI, set FLICKER_TOKEN as an env var instead — it takes priority over the stored file.

Quickstart

From zero to a deployed app and a forked database in five commands:

$ flicker auth login flk_xxx $ flicker database set my-app # write it to ./flicker.toml $ flicker branch create pr-1234 --ttl 2h --copy-all # fork db into the branch $ flicker deploy --from-local # build + rolling, health-gated deploy $ flicker branch delete pr-1234 -y # or let the TTL reaper handle it

Context: flicker.toml

Every command needs to know which org and database it acts on. Org is implicit in your token; database is named per call or set as a default. Resolution order (earlier wins):

--org / --database flag
./flicker.toml in the current directory
FLICKER_ORG / FLICKER_PROJECT env vars
~/.config/flicker/config.toml (global default)

Commit flicker.toml to the repo so the whole team and CI share one context without remembering flags:

# flicker.toml org = "acme" database = "my-app"

Databases & branches

A database is an isolated Postgres instance with a main branch. Branches are copy-on-write clones that come up in seconds and share storage until they diverge — the killer use case is a database per pull request. Protected branches (main by default) can't be deleted or reset.

$ flicker database create my-app # provision, wait until active $ flicker database import postgresql://… --database my-app # load an existing DB $ flicker branch create dev # fork off main $ flicker branch list # branches + connection strings $ flicker branch reset dev # re-fork (discard changes) $ flicker branch delete dev -y # permanent delete $ flicker ext enable vector # extensions, across all branches

branch create is idempotent on the name — re-running returns the existing branch instead of erroring.

Deploy an app

Point Flicker at a Dockerfile or a prebuilt image. Two modes, one command — both converge on the same rolling cutover: the new version only takes traffic once it's up, so a failed release leaves the old version serving:

$ flicker deploy # manifest mode — pinned image or [build] repo (CI) $ flicker deploy --from-local # tar the working dir, build + deploy (dev) $ flicker app logs web # tail container logs

Manifest mode reads [app] (plus optional [build] and [config]) from flicker.toml — reproducible and reviewable in a PR:

[app] name = "web" image = "myorg/web:v2" # OR a [build] table for source port = 8080 domain = "web.flicker.dev" # routed with automatic HTTPS [config] # literals + $refs into the env's secret pool PHX_HOST = "web.flicker.dev" # a committed literal STRIPE_KEY = "$STRIPE_KEY" # resolved from the bound environment's secrets

Secret $refs resolve from the app's bound environment — set the values with flicker secrets set STRIPE_KEY=… --environment production, never in flicker.toml.

Environments & secrets

Secrets live in named, org-level environments (production, preview/pr-42, dev/giovanni) — not on individual apps. Apps bind to one; every deploy resolves it into an immutable bundle. secrets set is one versioned change; values are never echoed back.

$ flicker secrets set STRIPE_KEY=sk_live_123 --environment production $ flicker secrets list --environment production # names + versions, never values $ flicker secrets pull # dev/<user> → ./.env $ flicker secrets diff # key-level status, never values

secrets get is the one deliberate value read — governed and access-logged; restricted secrets never return a value to anyone. The full model (inheritance, managed vs user secrets, bundles) is in the docs.

Read the environments & secrets guide

Preview environments in CI

branch ensure / branch destroy provision or tear down a whole preview for a git ref in one idempotent call — fork the database off the base, build the app from that ref, and wire up its env. Re-running on each push redeploys the same branch.

.github/workflows/preview.yml

on: pull_request steps: # one idempotent call brings up DB + app for this PR - run: flicker branch ensure --ref $BRANCH --base main --ttl 48h --label pr=$PR - run: ./test.sh # test against the preview # on merge/close — TTL reaper is the backstop if this never runs - run: flicker branch destroy --ref $BRANCH

TTL

--ttl 2h auto-expires the fork even if CI crashes.

Idempotency

Re-running create returns the existing branch, never a duplicate.

Labels

--label pr=1234 tags forks so you can find them later.

Tickets & memory

Flicker also includes an AI-native work ledger under each project. ticket commands manage recursive work items, append-only documents, and project memory without depending on chat history.

$ flicker project use my-project $ flicker ticket list --json $ flicker ticket create "Implement checkout" --body "Acceptance notes" $ flicker ticket document write 42 task_contract --body "$(cat plan.md)" $ flicker memory search "checkout conflict" --json $ flicker ticket checkout my-project --out .flicker/tickets

Workflow

Tickets use four canonical states and named transitions only: backlog, selected_for_dev, in_progress, done.

Evidence

Current document heads are current truth; older versions and events remain historical evidence.

Agents

Use local markdown checkout plus first-party skills like flicker-plan and flicker-implement.

The object model

The CLI grammar is always flicker <noun> <verb> <name>. The nouns nest left to right:

Organization: The tenant boundary. Every resource belongs to one; your API token pins which org you act as.
Project: The umbrella over databases, apps, environments, secrets, and tickets.
Database: An isolated Postgres instance with a main branch and any number of forks.
Branch: A copy-on-write clone of a parent branch. Comes up in seconds; its connection endpoint stays constant across renames.
Environment: A named, org-level bundle of governed secrets (production, preview/pr-42, dev/<user>) that apps and deploys resolve.
App: A container running over HTTPS, deployed from an image, a git repo, or your local working dir.
Ticket: A recursive work item under a project with canonical workflow state, documents, events, and searchable memory.

Full command reference — every flag and example

Get a token Back to overview