floci-cli

June 10, 2026 · View on GitHub

Official command-line interface for Floci — the free, open-source local cloud emulator for AWS and Azure.

# AWS (default)
floci start
eval $(floci env)
aws s3 mb s3://my-bucket

# Azure
floci az start
eval $(floci az env)
az storage container create --name mycontainer

Installation

Homebrew (macOS / Linux)

brew install floci-io/floci/floci

Install script (Linux / macOS)

curl -fsSL https://floci.io/install.sh | sh

Windows (PowerShell)

iwr https://floci.io/install.ps1 | iex

Scoop (Windows)

scoop bucket add floci https://github.com/floci-io/scoop-floci
scoop install floci

JVM fallback

Download floci.jar from the latest release and run:

java -jar floci.jar version

Quick Start

AWS

# Start Floci (AWS emulator)
floci start

# Check environment
floci doctor

# Export AWS environment variables
eval $(floci env)

# Use AWS services normally
aws s3 mb s3://my-bucket
aws dynamodb create-table --table-name users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

# Stop Floci
floci stop

Azure

# Start Floci Azure emulator
floci az start

# Check environment
floci az doctor

# Export Azure connection string
eval $(floci az env)

# Use Azure services
az storage container create --name mycontainer
az storage blob upload --container-name mycontainer --name hello.txt --data "hello"

# Stop Floci Azure
floci az stop

Switch default product

Bare commands like floci start route to the configured default product (AWS by default).

floci config default-product az   # make floci az the default
floci config default-product aws  # revert to aws

Command Reference

Commands are organized into two product groups — floci aws (or bare floci) and floci az. Both groups expose the same lifecycle commands.

Shared commands (product-independent)

CommandDescription
floci config showShow active configuration
floci config validateValidate a docker-compose.yml
floci config profileManage named profiles
floci config default-productSet the default product (aws or az)
floci completion bash|zshGenerate shell completion scripts

AWS commands (floci / floci aws)

CommandDescription
floci startLaunch the Floci AWS container
floci stopStop (and optionally remove) the container
floci restartStop then start
floci statusShow container state and server health
floci logsStream container logs
floci waitPoll until Floci is ready (CI-friendly)
floci versionShow CLI and server versions
floci servicesList enabled AWS services
floci doctorRun environment diagnostics
floci envPrint AWS environment variables
floci snapshot save/load/list/deleteManage state snapshots

Azure commands (floci az)

CommandDescription
floci az startLaunch the Floci Azure container
floci az stopStop (and optionally remove) the container
floci az restartStop then start
floci az statusShow container state and server health
floci az logsStream container logs
floci az waitPoll until Floci Azure is ready (CI-friendly)
floci az versionShow CLI and server versions
floci az servicesList enabled Azure services
floci az doctorRun Azure environment diagnostics
floci az envPrint Azure connection string / SDK env vars
floci az snapshotSnapshot commands (coming soon)

All commands support --help.

Global Flags

AWS global flags

--endpoint <url>            Floci server URL     (default: http://localhost:4566, env: FLOCI_ENDPOINT)
--container <name>          Container name       (default: floci, env: FLOCI_CONTAINER)
--output|-o text|json|yaml  Output format        (default: text)
--quiet, -q                 Suppress non-error output
--verbose, -v               Debug logging to stderr
--no-color                  Disable ANSI colors
--profile <name>            Load settings from ~/.floci/profiles/<name>.yaml

Azure global flags

--endpoint <url>            Floci Azure server URL  (default: http://localhost:4577, env: FLOCI_AZ_ENDPOINT)
--container <name>          Container name          (default: floci-az, env: FLOCI_AZ_CONTAINER)
--output|-o text|json|yaml  Output format           (default: text)
--quiet, -q                 Suppress non-error output
--verbose, -v               Debug logging to stderr
--no-color                  Disable ANSI colors

Port auto-detection — status, version, wait, and env automatically derive the correct endpoint from the container's port mapping. You don't need to pass --endpoint when using a non-default port, as long as --container points to the right container.

Commands

floci start / floci az start

Pulls the image (if needed), starts the container, and waits for readiness.

# AWS
floci start                          # default port 4566
floci start --port 4599              # custom host port
floci start --services s3,dynamodb   # enable specific services
floci start --persist ./data         # persist state to a host directory
floci start --pull always            # always pull the latest image
floci start --detach                 # return immediately, don't wait

# Azure
floci az start                       # default port 4577
floci az start --port 4578           # custom host port
floci az start --persist ./data      # persist state to a host directory

Docker daemon resolution (Podman, rootless, remote contexts)

The Floci container needs access to a Docker-compatible daemon (for Lambda, EC2, EKS, MSK, ECR, CodeBuild, and Kafka/Redpanda support). By default floci start bind-mounts /var/run/docker.sock, but it honors the standard DOCKER_HOST environment variable, so Podman, rootless setups, and remote Docker contexts work without extra flags:

# Rootless Podman
export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
floci start

# Rootful Podman
export DOCKER_HOST=unix:///run/podman/podman.sock
floci start

# Remote daemon over TCP
export DOCKER_HOST=tcp://10.0.0.5:2375
floci start

Resolution precedence:

  1. DOCKER_HOST — the standard Docker/Podman variable (unix:// socket, tcp:// daemon, or npipe:// on Windows)
  2. DOCKER_SOCK — legacy override (a bare socket path)
  3. OS default — /var/run/docker.sock on Linux/macOS, or the Docker named pipe on Windows

For a unix:// socket the resolved path is bind-mounted into the container; for a remote tcp:// daemon the DOCKER_HOST value is passed through to the container instead. Run floci doctor to see which endpoint was resolved.

floci stop / floci az stop

floci stop                    # graceful stop (10s timeout)
floci stop --timeout 30       # wait up to 30s before force-kill
floci stop --remove           # also remove the container after stopping

floci status / floci az status

floci status                          # auto-detects endpoint from container port mapping
floci status --container myfloci      # target a specific container
floci status -o json                  # structured output

floci env

Prints AWS environment variables pointing at the running Floci instance. The default hostname is localhost.floci.io (resolves to 127.0.0.1, enables virtual-hosted S3 bucket names).

eval $(floci env)                          # bash/zsh — sets all four AWS vars
floci env --shell fish | source            # fish
floci env --shell powershell | Invoke-Expression  # PowerShell

floci env --host myhost.local              # custom hostname
floci env --region eu-west-1              # custom region (default: us-east-1)
floci env -o json                          # structured output for scripts

Variables exported:

VariableDefault value
AWS_ENDPOINT_URLhttp://localhost.floci.io:<port>
AWS_ACCESS_KEY_IDtest
AWS_SECRET_ACCESS_KEYtest
AWS_DEFAULT_REGIONus-east-1

floci az env

Prints Azure connection variables for the running Floci Azure instance.

eval $(floci az env)                                # connection string (default)
eval $(floci az env --format sdk-vars)              # individual SDK endpoint vars
eval $(floci az env --format sdk-vars --service blob,queue)  # specific services only

floci az env --shell fish | source                  # fish
floci az env -o json                                # structured output

Connection string mode (default) exports:

VariableValue
AZURE_STORAGE_CONNECTION_STRINGFull Azurite-compatible connection string

SDK vars mode (--format sdk-vars) exports:

VariableDefault value
AZURE_STORAGE_ACCOUNTdevstoreaccount1
AZURE_STORAGE_KEYAzurite dev key
AZURE_STORAGE_BLOB_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1
AZURE_STORAGE_QUEUE_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1-queue
AZURE_STORAGE_TABLE_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1-table
AZURE_FUNCTIONS_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1-functions
AZURE_APP_CONFIGURATION_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1-appconfig
AZURE_KEY_VAULT_ENDPOINThttp://localhost.floci.io:<port>/devstoreaccount1-keyvault

floci logs / floci az logs

floci logs                       # last logs from the container
floci logs --tail 50             # last 50 lines
floci logs --since 5m            # logs from the last 5 minutes
floci logs --follow              # stream live logs (Ctrl-C to stop)

floci wait / floci az wait

floci wait                        # wait up to 30s (default)
floci wait --timeout 2m           # custom timeout (supports s, m, h)
floci wait --service dynamodb     # wait until a specific service is ready
floci wait -o json                # machine-readable output

floci doctor / floci az doctor

floci doctor                      # run all checks
floci doctor --check docker.installed   # run a single check by name
floci doctor --fix                # auto-fix fixable issues
floci doctor -o json              # structured output for scripts

floci az doctor                   # Azure-specific checks (includes az CLI + connection string)

floci version / floci az version

floci version                     # CLI version, server version, image digest
floci version -o json

floci services / floci az services

floci services                    # list all enabled services
floci services -o json

floci config

floci config show                          # show active configuration
floci config default-product aws|az        # set the default product (persisted to ~/.floci/config.yaml)
floci config profile list                  # list saved profiles
floci config profile create <name>         # create a new profile
floci config profile show <name>           # show a profile
floci config profile delete <name>         # delete a profile
floci config validate -f docker-compose.yml  # validate a Compose file

Profiles are stored in ~/.floci/profiles/<name>.yaml and can override any global option. Use --profile <name> on any command to load one.

floci snapshot

Save and restore named snapshots of Floci AWS state.

floci snapshot list
floci snapshot save <name> --message "before migration"
floci snapshot load <name>
floci snapshot delete <name>
floci snapshot export <name> -o tarball.tar.gz
floci snapshot import tarball.tar.gz

Azure snapshots (floci az snapshot) are not yet available — they require server-side endpoints not yet implemented in Floci Azure.

floci completion

floci completion bash >> ~/.bashrc
floci completion zsh  >> ~/.zshrc

CI Usage

AWS CI

floci start --detach
floci wait --timeout 60s
eval $(floci env)
pytest  # or your test command
floci stop --remove

With Docker Compose:

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Using Podman or a non-default daemon? Swap the host side of the socket mount for your daemon's socket (e.g. /run/user/1000/podman/podman.sock:/var/run/docker.sock). With the CLI, setting DOCKER_HOST is enough — see Docker daemon resolution.

Azure CI

floci az start --detach
floci az wait --timeout 60s
eval $(floci az env)
pytest  # or your test command
floci az stop --remove

With Docker Compose:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Scope

floci-cli manages Floci's lifecycle, config, state, and diagnostics. It does not wrap the AWS CLI, Azure CLI, or manage cloud resources directly. Use aws with AWS_ENDPOINT_URL or az with the appropriate connection string for resource operations.

License

MIT — see LICENSE.