Skip to Content
dFlow

Day-one with dflow

Register, set context, deploy, build, databases, and cleanup efficiently.

One path from an empty laptop to a running URL on the platform API. Defaults use https://k8s.dflow.sh until login saves another origin.

Install and probe

curl -fsSL https://github.com/dflow-sh/dflow/releases/latest/download/install.sh | sh
dflow version
dflow api:ready --api https://k8s.dflow.sh

When stdout is a pipe or you pass --progress plain, the CLI prints [phase] lines on stderr and, for builds, the build log on stdout so CI logs stay readable.

Account and context

dflow auth:register and dflow login need an interactive TTY. They prompt for a password and do not accept --password. Use a normal terminal, or dflow login --token-stdin for automation after you have a workspace token. dflow login --google and dflow login --github sign in when the server has that provider. They print a URL and do not replace password signup.

dflow auth:register --email you@example.com
# password at the prompt (12–128 characters)
# When the API requires email verification, run: dflow auth:verify TOKEN_FROM_EMAIL

dflow login --email you@example.com
dflow whoami
dflow context:show

Create a team workspace (the personal workspace stays private). Creating a project selects it. Creating an environment selects it.

dflow workspaces:create team
dflow projects:create gate
dflow environments:create live --region eu

dflow projects:create gate --environment live --region eu creates both and selects them. The two commands above stay the way to create the environment later.

dflow context:use --workspace team --project gate --environment live still saves that scope when you want to set it yourself. The CI example below uses it that way.

Workspace tokens

dflow tokens:create --role developer --expires-in 90d
dflow tokens:list

Deploy from an image

hashicorp/http-echo exits unless ECHO_TEXT is set. Set it before the first deploy. Before the first deploy, apps:env:set only stores the value (status stored); it applies on the first deploy.

dflow apps:create web
dflow apps:env:set web ECHO_TEXT=hello --wait --wait-timeout 10m
dflow apps:deploy web --image hashicorp/http-echo:1.0.0 --port 5678 \
  --cpu-millicores 200 --memory-mi 256 \
  --wait --wait-timeout 10m
dflow apps:route:set web --wait --wait-timeout 10m
host=$(dflow apps:route:show web --output json | jq -r .host)
curl -fsS "https://${host}"

Use the host from dflow apps:route:show (or the route table after apps:route:set --wait). Do not construct web-PROJECT-ENV.apps... by hand. The platform may add a four-character suffix when that name is already taken elsewhere on the cluster.

Deploy from source

Default wait is short. Builds need a longer timeout. Set ECHO_TEXT before build so the container stays up. A public GitHub repository builds with no stored token. Store a token only for private repositories:

printf '%s' "$GITHUB_PAT" | dflow github:token:set
dflow github:token:show
dflow apps:create echo
dflow apps:env:set echo ECHO_TEXT=hello-from-build --wait --wait-timeout 10m
dflow apps:build echo --repo https://github.com/hashicorp/http-echo --port 5678 \
  --wait --wait-timeout 20m
dflow apps:route:set echo --wait --wait-timeout 10m

A directory on this machine uses the same build. The packed upload is at most 100MB. .git, node_modules, and .env are skipped. .env.example stays. Do not pass --repo and --path together.

dflow apps:build web --path ./web --wait --wait-timeout 20m

Restart the running pods without a new release:

dflow apps:restart web --wait --wait-timeout 10m

Routes, env, secrets, logs

dflow apps:env:get web
printf 'secret' | dflow apps:secret:set web DEMO_KEY --wait --wait-timeout 10m
dflow apps:secret:list web
dflow apps:logs web --tail 50
dflow apps:events web
dflow apps:events:pods web

Custom hostname (must not sit under the platform apps suffix):

dflow apps:route:set web --host app.example.com --wait --wait-timeout 15m

Jobs, volumes, releases

dflow jobs:create --app web --name once \
  --image postgres:16-alpine --command postgres --command --version \
  --wait-timeout 5m
dflow volumes:create --app web --name data --mount-path /data --size-gi 1 --storage-class local-path
dflow apps:releases:list web

PostgreSQL

dflow db:postgres:create appdb --database appdb --app web --storage 1Gi \
  --wait --wait-timeout 15m
dflow db:list
dflow db:credentials appdb
dflow db:redis:create cache --app web --wait --wait-timeout 15m
dflow db:backups:create appdb --wait --wait-timeout 15m
dflow db:backups:list appdb

Official templates:

dflow templates:list
dflow templates:install umami

templates:install can take several minutes. It prints generated secrets such as secret.password and secret.APP_SECRET once. Save them before you close the terminal.

Workspace invites

dflow invites:create colleague@example.com --role developer
dflow invites:accept INVITE_TOKEN
dflow members:list
dflow members:role USER_ID developer
dflow members:remove USER_ID --confirm-email colleague@example.com

members:role and members:remove are refused on the personal workspace. Remove asks for that member's email.

Cleanup (destructive)

Confirm names match the application or service. There is no projects:delete or workspace delete command yet.

dflow volumes:delete data --app web --confirm data
dflow apps:delete echo --confirm-name echo --wait --wait-timeout 10m
dflow apps:delete web --confirm-name web --wait --wait-timeout 10m
dflow db:delete appdb --confirm-name appdb --wait --wait-timeout 10m
dflow tokens:revoke TOKEN_ID --confirm PREFIX

If you added a custom route hostname, delete it with dflow apps:route:delete web HOST --wait --wait-timeout 10m. Delete template applications the same way when you no longer need them.

Use dflow in CI

Store a workspace token in the CI secret store. Do not pass passwords on the command line.

export DFLOW_API=https://k8s.dflow.sh
printf '%s' "$DFLOW_TOKEN" | dflow login --token-stdin --context ci --api "$DFLOW_API"
dflow --context ci whoami
dflow --context ci context:use --workspace team --project gate --environment live
dflow --context ci apps:deploy web \
  --image "$IMAGE" --port 5678 --wait --wait-timeout 10m --output json

Use --output json in scripts and fail when status is failed. Image deploys and env changes accept --wait, --wait-timeout, and --progress auto|tty|plain. While --wait runs, build output streams on stdout, phases on stderr (or a spinner when stderr is a TTY), and rollout pod events as indented lines:

⠹ rolling_out 42s
  pod web-7d9f Pulling image
Building with Railpack 0.43.0
Pushing image
✓ building 1m12s
summary   succeeded in 2m04s
app       web
release   ghcr.io/org/web:main-abc
url       https://web-demo-staging.apps.example.test

apps:route:set --wait waits until TLS is ready (and the hostname answers over HTTPS) on the host you set with --host, or on the platform hostname when --host is omitted, before it prints the route table.

How is this guide?

Last updated on

On this page