floci-cli

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

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

# GCP
floci gcp start
eval $(floci gcp env)
gcloud storage buckets create gs://my-bucket

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

# OCI
floci oci start
floci oci setup
eval $(floci oci env)
oci os ns get

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 it (requires Java 25+):

java -jar floci.jar version

Staying up to date

Native-binary installs (install script, direct download) can self-update:

floci update --check   # exit 0: up to date, exit 1: update available
floci update           # download, verify checksum, replace the binary

Homebrew and Scoop installs are updated through their package manager (brew upgrade floci) — floci update detects Homebrew-managed binaries and refuses to touch them.

---

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

GCP

# Start Floci GCP emulator
floci gcp start

# Check environment
floci gcp doctor

# Export GCP emulator host variables
eval $(floci gcp env)

# Use GCP services normally
gcloud storage buckets create gs://my-bucket
gcloud pubsub topics create my-topic

# Stop Floci GCP
floci gcp 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

OCI

# Start Floci OCI emulator
floci oci start

# Check environment
floci oci doctor

# One-time: create a throwaway OCI CLI profile (API key + ~/.oci/config)
floci oci setup

# Export OCI endpoint variables
eval $(floci oci env)

# Use OCI services normally
oci os ns get
oci os bucket create --namespace-name floci-local --name my-bucket \
  --compartment-id ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000

# Stop Floci OCI
floci oci stop

Switch default product

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

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

---

Command Reference

Commands are organized into four product groups — floci aws (or bare floci), floci gcp, floci az, and floci oci. All groups expose the same lifecycle commands.

Shared commands (product-independent)

Command	Description
floci config show	Show active configuration
floci config validate	Validate a docker-compose.yml
floci config profile	Manage named profiles
floci config default-product	Set the default product (aws, gcp, az, or oci)
floci update	Self-update the CLI to the latest release
floci completion bash|zsh	Generate shell completion scripts
floci update	Update the CLI to the latest release

AWS commands (floci / floci aws)

Command	Description
floci start	Launch the Floci AWS container
floci stop	Stop (and optionally remove) the container
floci restart	Stop then start
floci status	Show container state and server health
floci logs	Stream container logs
floci wait	Poll until Floci is ready (CI-friendly)
floci version	Show CLI and server versions
floci services	List enabled AWS services
floci doctor	Run environment diagnostics
floci env	Print AWS environment variables
floci snapshot save/load/list/delete	Manage state snapshots

GCP commands (floci gcp)

Command	Description
floci gcp start	Launch the Floci GCP container
floci gcp stop	Stop (and optionally remove) the container
floci gcp restart	Stop then start
floci gcp status	Show container state and server health
floci gcp logs	Stream container logs
floci gcp wait	Poll until Floci GCP is ready (CI-friendly)
floci gcp version	Show CLI and server versions
floci gcp services	List enabled GCP services
floci gcp doctor	Run GCP environment diagnostics
floci gcp env	Print GCP SDK emulator host variables
floci gcp snapshot	Snapshot commands (coming soon)

Azure commands (floci az)

Command	Description
floci az start	Launch the Floci Azure container
floci az stop	Stop (and optionally remove) the container
floci az restart	Stop then start
floci az status	Show container state and server health
floci az logs	Stream container logs
floci az wait	Poll until Floci Azure is ready (CI-friendly)
floci az version	Show CLI and server versions
floci az services	List enabled Azure services
floci az doctor	Run Azure environment diagnostics
floci az env	Print Azure connection string / SDK env vars
floci az snapshot	Snapshot commands (coming soon)

OCI commands (floci oci)

Command	Description
floci oci start	Launch the Floci OCI container
floci oci stop	Stop (and optionally remove) the container
floci oci restart	Stop then start
floci oci status	Show container state and server health
floci oci logs	Stream container logs
floci oci wait	Poll until Floci OCI is ready (CI-friendly)
floci oci version	Show CLI and server versions
floci oci services	List enabled OCI services
floci oci doctor	Run OCI environment diagnostics
floci oci env	Print OCI endpoint variables
floci oci setup	Create a local OCI CLI profile (API key + ~/.oci/config)
floci oci snapshot	Snapshot 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

GCP global flags

--endpoint <url>            Floci GCP server URL    (default: http://localhost:4588, env: FLOCI_GCP_ENDPOINT)
--container <name>          Container name          (default: floci-gcp, env: FLOCI_GCP_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
--profile <name>            Load settings from ~/.floci/profiles/<name>.yaml

OCI global flags

--endpoint <url>            Floci OCI server URL    (default: http://localhost:4599, env: FLOCI_OCI_ENDPOINT)
--container <name>          Container name          (default: floci-oci, env: FLOCI_OCI_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

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 gcp start / floci az start / floci oci start

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

# AWS
floci start                          # default port 4566
floci start --port 4567              # 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

# GCP
floci gcp start                      # default port 4588
floci gcp start --persist ./data     # persist state to a host directory

# 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

# OCI
floci oci start                      # default port 4599
floci oci 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 gcp stop / floci az stop / floci oci 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 gcp status / floci az status / floci oci 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:

Variable	Default value
AWS_ENDPOINT_URL	http://localhost.floci.io:<port>
AWS_ACCESS_KEY_ID	test
AWS_SECRET_ACCESS_KEY	test
AWS_DEFAULT_REGION	us-east-1

floci gcp env

Prints GCP SDK emulator host variables for the running Floci GCP instance.

eval $(floci gcp env)                        # all emulator host vars
eval $(floci gcp env --service gcs,pubsub)   # specific services only

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

Variables exported (per enabled service):

Variable	Service
STORAGE_EMULATOR_HOST	Cloud Storage (gcs)
PUBSUB_EMULATOR_HOST	Pub/Sub
FIRESTORE_EMULATOR_HOST	Firestore
DATASTORE_EMULATOR_HOST	Datastore
SECRET_MANAGER_EMULATOR_HOST	Secret Manager
IAM_EMULATOR_HOST	IAM

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:

Variable	Value
AZURE_STORAGE_CONNECTION_STRING	Full Azurite-compatible connection string

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

Variable	Default value
AZURE_STORAGE_ACCOUNT	devstoreaccount1
AZURE_STORAGE_KEY	Azurite dev key
AZURE_STORAGE_BLOB_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1
AZURE_STORAGE_QUEUE_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1-queue
AZURE_STORAGE_TABLE_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1-table
AZURE_FUNCTIONS_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1-functions
AZURE_APP_CONFIGURATION_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1-appconfig
AZURE_KEY_VAULT_ENDPOINT	http://localhost.floci.io:<port>/devstoreaccount1-keyvault

floci oci env

Prints OCI endpoint variables for the running Floci OCI instance. OCI SDKs and the oci CLI take a single endpoint for every service, so no per-service variables are needed.

eval $(floci oci env)                        # endpoint vars for CLI, wrappers, and Terraform

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

Variables exported:

Variable	Purpose
OCI_CLI_ENDPOINT	Default --endpoint for the oci CLI
FLOCI_OCI_ENDPOINT	Used by this CLI and the ocilocal wrapper
TF_VAR_CLIENT_HOST_OVERRIDES	Per-client host overrides for the oracle/oci Terraform provider
OCI_CLI_PROFILE	The profile floci oci setup wrote (default FLOCI) — only exported when detected in ~/.oci/config, and skipped for DEFAULT

floci oci setup

The OCI CLI and SDKs refuse to run without a config file and an API signing key — even against an emulator that never validates them. floci oci setup creates both in one step: a locally generated RSA-2048 key at ~/.oci/floci_key.pem and a [FLOCI] profile in ~/.oci/config with the emulator's canonical throwaway tenancy. Existing profiles are never touched; re-running is a no-op.

floci oci setup                        # create key + [FLOCI] profile
floci oci setup --profile-name DEFAULT # write a different profile section
floci oci setup -o json                # structured output

# then connect:
eval $(floci oci env)                  # exports OCI_CLI_PROFILE=FLOCI too
oci os ns get

floci logs / floci gcp logs / floci az logs / floci oci 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 gcp wait / floci az wait / floci oci 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 gcp doctor / floci az doctor / floci oci 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 gcp doctor                  # GCP-specific checks
floci az doctor                   # Azure-specific checks (includes az CLI + connection string)
floci oci doctor                  # OCI-specific checks

floci version / floci gcp version / floci az version / floci oci version

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

floci services / floci gcp services / floci az services / floci oci services

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

floci config

floci config show                          # show active configuration
floci config default-product aws|gcp|az|oci  # 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>
floci snapshot load <name>
floci snapshot delete <name>
floci snapshot export <name> -o tarball.tar.gz
floci snapshot import tarball.tar.gz

GCP, Azure, and OCI snapshots (floci gcp snapshot / floci az snapshot / floci oci snapshot) require server-side endpoints not yet implemented in Floci GCP / Floci Azure / Floci OCI — until then those commands report the missing API and exit 1. floci snapshot export|import (AWS) are also pending server support and exit 1.

floci update

Self-updates a native-binary install to a newer release (checksum-verified, atomic replace).

floci update                      # update to the latest release
floci update --check              # only report; exit 0 = up to date, 1 = update available
floci update --version 0.1.8      # pin a specific version

floci update --check || floci update   # script-friendly: update only when stale

Homebrew-managed installs are refused — use brew upgrade floci instead.

floci completion

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

floci update

Self-update the CLI in place: downloads the release binary from GitHub, verifies its sha256 against the release's sha256sums.txt, and atomically replaces the running binary.

floci update                      # update to the latest release
floci update --check              # exit 0: up to date, exit 1: update available
floci update --version 0.1.7      # install a specific version

Homebrew installs are managed by brew and are detected and refused — use brew upgrade floci there instead.

When run from an interactive terminal, floci also checks for new releases in the background (at most once per 24h, cached in ~/.floci/update-check.json) and prints a hint before the command output when one is available. Set FLOCI_NO_UPDATE_CHECK=1 to opt out; the check is automatically disabled in CI and for piped output.

---

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.

GCP CI

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

With Docker Compose:

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

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

OCI CI

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

With Docker Compose:

services:
  floci-oci:
    image: floci/floci-oci:latest
    ports:
      - "4599:4599"
    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, GCP, Azure, or OCI CLIs, or manage cloud resources directly. Use aws with AWS_ENDPOINT_URL, gcloud/SDKs with the emulator host variables, az with the appropriate connection string, or oci with OCI_CLI_ENDPOINT for resource operations.

---

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to build, test, and submit changes.

---

License

MIT — see LICENSE.