floci
Any Cloud. Locally. Floci CLI to manage local cloud emulators.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/floci-io--floci-cli)HTML
<a href="/listings/floci-io--floci-cli"><img src="/api/listings/floci-io--floci-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
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
JVM fallback
Download `floci.jar` from the [latest release](https://github.com/floci-io/floci-cli/releases/latest) 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, 1: update available, 2: the check failed floci update # download, verify checksum, replace the binary
Homebrew installs are updated through Homebrew (`brew upgrade floci`); `floci update` detects Homebrew-managed binaries and refuses to touch them.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 21 lines
- {
- "name": "floci",
- "owner": {
- "name": "Floci",
- "url": "https://floci.io"
- },
- "metadata": {
- "description": "Agent skills for Floci, the free local emulators for AWS, GCP, Azure and OCI"
- },
- "plugins": [
- {
- "name": "floci",
- "description": "Run, wire up and troubleshoot the Floci local cloud emulators with floci-cli, docker run or Docker Compose",
- "source": "./",
- "strict": false,
- "skills": [
- "./skills/floci"
- ]
- }
- ]
- }
README.md · README · 1,219 lines · 2 findings marked
- <p align="center">
- <img src="https://raw.githubusercontent.com/floci-io/.github/main/floci.svg#gh-light-mode-only" alt="Floci" width="500" />
- <img src="https://github.com/user-attachments/assets/edfff8b3-926c-471e-9549-77fb90a21b49#gh-dark-mode-only" alt="Floci" width="500" />
- </p>
- <p align="center">
- <strong>Any Cloud. Locally.</strong><br />
- Light, fluffy, and always free: the Floci command-line interface<br />
- No account. No auth token. No feature gates.
- </p>
- <p align="center">
- <a href="https://github.com/floci-io/floci-cli/releases/latest"><img src="https://img.shields.io/github/v/release/floci-io/floci-cli?label=release&color=blue" alt="Latest release"></a>
- <a href="https://github.com/floci-io/floci-cli/actions/workflows/ci.yml"><img src="https://github.com/floci-io/floci-cli/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
- <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
- <a href="https://github.com/floci-io/floci-cli/stargazers"><img src="https://img.shields.io/github/stars/floci-io/floci-cli?style=flat" alt="GitHub Stars"></a>
- </p>
- <p align="center">
- <a href="#installation">Install</a> ·
- <a href="#quick-start">Quick Start</a> ·
- <a href="#command-reference">Commands</a> ·
- <a href="#the-floci-emulators">Emulators</a> ·
- <a href="https://floci.io">Docs</a>
- </p>
- ---
- ## What is this?
- `floci-cli` is the official command-line interface for [Floci](https://github.com/floci-io), the free, open-source
- local cloud emulators. It starts, stops, configures and diagnoses the emulator containers, and prints the
- environment your cloud CLI or SDK needs to talk to them. It does not manage cloud resources itself; your usual
- `aws`, `gcloud`, `az` and `oci` tools do that against the emulator (see [Scope](#scope)).
- ```sh
- # 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
- floci az setup
- eval $(floci az env)
- az storage container create --name mycontainer
- az group create -n my-rg -l westeurope
- # OCI
- floci oci start
- floci oci setup
- eval $(floci oci env)
- oci os ns get
- ```
- ### The Floci emulators
- floci-cli drives every member of the [Floci](https://github.com/floci-io) emulator family. Floci is named after
- [floccus](https://en.wikipedia.org/wiki/Cirrocumulus_floccus), the cloud formation that looks like popcorn.
- | Emulator | Cloud | Port | CLI tree |
- |----------------------------------------------------|-------|:----:|----------------------------------|
- | [floci](https://github.com/floci-io/floci) | AWS | 4566 | `floci` / `floci aws` (default) |
- | [floci-az](https://github.com/floci-io/floci-az) | Azure | 4577 | `floci az` |
- | [floci-gcp](https://github.com/floci-io/floci-gcp) | GCP | 4588 | `floci gcp` |
- | [floci-oci](https://github.com/floci-io/floci-oci) | OCI | 4599 | `floci oci` |
- ## Installation
- ### Homebrew (macOS / Linux)
- ```sh
- brew install floci-io/floci/floci
- ```
- ### Install script (Linux / macOS)
- ```sh
- curl -fsSL https://floci.io/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 84 on GitHub
- ```
- ### Windows (PowerShell)
- ```powershell
- iwr https://floci.io/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 90 on GitHub
- ```
- ### JVM fallback
- Download `floci.jar` from the [latest release](https://github.com/floci-io/floci-cli/releases/latest) and run it (requires **Java 25+**):
- ```sh
- java -jar floci.jar version
- ```
- ### Staying up to date
- Native-binary installs (install script, direct download) can self-update:
- ```sh
- floci update --check # exit 0: up to date, 1: update available, 2: the check failed
- floci update # download, verify checksum, replace the binary
- ```
- Homebrew installs are updated through Homebrew (`brew upgrade floci`); `floci update` detects Homebrew-managed binaries and refuses to touch them.
- ---
- ## Quick Start
- ### AWS
- ```sh
- # 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
- ```sh
- # 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
- ```sh
- # Start Floci Azure emulator
- floci az start
- # Check environment
- floci az doctor
- # Point the az CLI at the emulator (certificate, cloud, login)
- floci az setup
- # Export the connection string and the az CLI config
- 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"
- az group create -n my-rg -l westeurope
- # Stop Floci Azure
- floci az stop
- ```
- ### OCI
- ```sh
- # 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).
- ```sh
- 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 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 |
- ### 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 reset` | Delete every resource in the running emulator, keeping it running |
- | `floci doctor` | Run environment diagnostics |
- | `floci env` | Print AWS environment variables |
- | `floci snapshot save/load/list/delete` | Manage state snapshots |
- | `floci config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (AWS defaults) |
- Bare `floci config ...` always means the AWS tree, whatever the default product; use
- `floci gcp config ...` and so on for the others.
- ### 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 reset` | Delete every resource in the running emulator, keeping it running |
- | `floci gcp doctor` | Run GCP environment diagnostics |
- | `floci gcp env` | Print GCP SDK emulator host variables |
- | `floci gcp snapshot` | Snapshot commands (coming soon) |
- | `floci gcp config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (GCP defaults) |
- ### 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 reset` | Delete every resource in the running emulator, keeping it running |
- | `floci az doctor` | Run Azure environment diagnostics |
- | `floci az env` | Print Azure connection string / SDK env vars |
- | `floci az setup` | Point the `az` CLI at the emulator: trust its certificate, register the cloud, log in |
- | `floci az snapshot` | Snapshot commands (coming soon) |
- | `floci az config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (Azure defaults) |
- ### 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 reset` | Delete every resource in the running emulator, keeping it running |
- | `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) |
- | `floci oci config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (OCI defaults) |
- All commands support `--help`.
- ---
- ## Global Flags
- Every tree takes the same flags; only the defaults differ. With `--json` (or `-o json`, `-o yaml`)
- a command prints one document on stdout and nothing else. When a command cannot do what it was
- asked, the error is on stderr and stdout is empty. Exit `1` does not always mean that, though:
- `doctor`, `status` and `config validate` answer a question, and `start` and `restart` report on a
- container they did create, so each still prints its document when the answer is "no" (a failed
- check, an instance that is down, a file with errors, a start that never became ready). `wait`
- prints nothing when it times out. Read the exit code first, then the document.
- Two commands print text whatever the format, because their output is not a document: `logs` (the
- container's own output) and `completion` (a script). `env` prints shell
- code in text mode and the variables as a map in JSON or YAML. Marks are plain ASCII without
- `--no-emoji` too whenever the output is not a terminal (a pipe, a file, CI logs) or `NO_COLOR` is
- set. `--json` wins when it is combined with `--output`.
- ### 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)
- --json Shorthand for --output json
- --quiet, -q Suppress non-error output
- --verbose, -v Debug logging to stderr
- --no-color Disable ANSI colors
- --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
- --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
- ```
- Explicit flags override the profile; the profile overrides the environment variables.
- ### 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)
- --json Shorthand for --output json
- --quiet, -q Suppress non-error output
- --verbose, -v Debug logging to stderr
- --no-color Disable ANSI colors
- --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
- --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
- ```
- Explicit flags override the profile; the profile overrides the environment variables.
- ### 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)
- --json Shorthand for --output json
- --quiet, -q Suppress non-error output
- --verbose, -v Debug logging to stderr
- --no-color Disable ANSI colors
- --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
- --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
- ```
- Explicit flags override the profile; the profile overrides the environment variables.
- ### 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)
- --json Shorthand for --output json
- --quiet, -q Suppress non-error output
- --verbose, -v Debug logging to stderr
- --no-color Disable ANSI colors
- --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
- --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
- ```
- Explicit flags override the profile; the profile overrides the environment variables.
- > **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.
- ```sh
- # 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
- floci start --namespace team-b # scope the containers it launches (see below)
- # GCP
- floci gcp start # default port 4588
- floci gcp start --persist ./data # persist state to a host directory
- floci gcp start --namespace team-b # scope the containers it launches
- # 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
- floci az start --namespace team-b # scope the containers it launches
- # OCI
- floci oci start # default port 4599
- floci oci start --persist ./data # persist state to a host directory
- floci oci start --namespace team-b # scope the containers it launches
- ```
- `--namespace` sets the emulator's Docker resource namespace (`FLOCI_DOCKER_RESOURCE_NAMESPACE`,
- `FLOCI_GCP_…`, `FLOCI_AZ_…`, `FLOCI_OCI_…`). The emulator puts it in the names and the
- `floci_namespace` label of the containers and volumes it launches (Lambda, ECS, RDS, Cloud Run,
- Service Bus, ...) and only cleans up leftovers in its own namespace. When `--container` is not the
- product default, the namespace is derived from it, without the default-container prefix the
- emulator already adds (`floci-gcp-b` → `b`, so children are `floci-gcp-b-…`; `team-b` stays
- `team-b`). The default container gets none.
- On a `--port` other than the product default, `start` also sets the emulator's base URL
- (`FLOCI_BASE_URL`, `FLOCI_GCP_BASE_URL`, ...) to the endpoint with that port (`http://localhost:<port>`
- unless `--endpoint` names another host), so URLs it returns
- (SQS `QueueUrl`, presigned URLs, the OCI functions invoke endpoint) point at that instance.
- #### 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:
- ```sh
- # 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.
- With `podman machine` on macOS, the socket on the Mac (the one `podman machine start` prints) is
- a forwarder, and the container runs inside the VM, where that path is not the daemon's socket.
- When the daemon is Podman, `floci start` asks `podman info` for the socket the daemon listens on
- inside the VM (`/run/podman/podman.sock` rootful, `/run/user/<uid>/podman/podman.sock` rootless)
- and mounts that instead, so this needs the `podman` CLI on `PATH`. Set `DOCKER_SOCK` to choose
- the mounted socket yourself: on macOS it is the mount even when `DOCKER_HOST` is set, and podman
- is not asked.
- With SELinux enforcing (for example the Fedora VM behind `podman machine`), the container's label
- keeps Floci from connecting to the socket, and the web console fails to start with
- `java.net.BindException: Permission denied`. Relabeling the mount with `:z` is not enough: it fixes
- access to the socket file, but SELinux also checks the daemon on the other end of the socket. Turn
- labeling off for the Floci container instead:
- ```sh
- floci start --security-opt label=disable
- ```
- `--security-opt` is passed to `docker run` unchanged and can be repeated. Without `--profile`,
- `floci restart` passes back the options `docker inspect` reports for the running container. With
- `--profile` it starts from the profile, which has no key for them: run
- `floci <product> stop --profile <name> --remove`, then
- `floci <product> start --profile <name> --security-opt ...`, where `<product>` is the profile's
- `aws`, `gcp`, `az` or `oci`.
- ### `floci stop` / `floci gcp stop` / `floci az stop` / `floci oci stop`
- ```sh
- floci stop # graceful stop (10s timeout)
- floci stop --timeout 30 # wait up to 30s before force-kill
- floci stop --timeout -1 # never force-kill: wait for the container to exit
- floci stop --remove # also remove the container after stopping
- floci stop -o json # {"container", "state", "stopped", "removed"}
- ```
- `start`, `stop` and `restart` print one document with `-o json` or `-o yaml` and nothing else on
- stdout: the progress lines are left out and docker's pull progress goes to stderr. `start` and
- `restart` report `container`, `id`, `image`, `endpoint`, `state` and `ready` (`ready` is absent
- with `--detach`). `logs` prints the container's own output and stays plain text.
- If `restart` fails after removing the old container, stderr includes a `start` command with
- the resolved container, port, image, endpoint, persistence, services and namespace settings.
- It also appears with structured output. Review the failure, then run that command to retry. If
- the new container is running but did not become ready, stderr instead says to check `logs` and
- run `wait`, because `start` refuses a running container.
- A selected container with no published port and no configured endpoint has no known endpoint.
- `status` does not probe the default instance and reports `endpoint: null` in structured output.
- `env`, `services`, `az setup` and the `snapshot` commands exit `1` with the next step rather than
- act on the default instance. `doctor` and `version` still run and do not probe it. `wait` keeps
- looking for the container until `--timeout`.
- A profile's `port` supplies its endpoint when the endpoint is unset or still the product default.
- A running container's published port corrects that endpoint, unless the endpoint was chosen on
- purpose: typed with `--endpoint`, set in `FLOCI_ENDPOINT`, or on another host. `env` warns on stderr
- when it looked the container up and it is not running.
- ### `floci status` / `floci gcp status` / `floci az status` / `floci oci status`
- ```sh
- floci status # auto-detects endpoint from container port mapping
- floci status --container myfloci # target a specific container
- floci status -o json # structured output
- floci status >/dev/null && echo up # exit 0: the instance is up, exit 1: it is not
- ```
- `status` exits 0 when the server answers and its container, if there is one, is running, and 1
- otherwise, in every output format. An instance with no local container (a remote `--endpoint`, a
- Compose service under another name) counts as up when it answers.
- ### `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).
- ```sh
- 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.
- ```sh
- 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 |
- SDK support for these variables varies by service and language. Python Secret Manager ignores
- `SECRET_MANAGER_EMULATOR_HOST`; set an explicit emulator endpoint and anonymous credentials.
- See the [Python Secret Manager recipe](skills/floci/references/gcp.md#python-secret-manager).
- ### `floci az env`
- Prints Azure connection variables for the running Floci Azure instance.
- The connection string contains `;` separators, so the emitted value is single-quoted (as it is in every tree's `env` output) and is safe to `eval`.
- ```sh
- 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` |
- **After `floci az setup`**, both modes also export:
- | Variable | Value |
- |----------|-------|
- | `AZURE_CONFIG_DIR` | `~/.floci/az/<container>/azure-config`, the instance's isolated az config; after `--global` it is unset instead, so a value left by another instance's `eval` does not linger |
- | `REQUESTS_CA_BUNDLE` | `~/.floci/az/<container>/ca-bundle.pem`, the public roots plus that instance's certificate |
- If the instance's certificate changed since setup (a container recreated without `--persist`),
- `floci az env` warns on stderr and tells you to re-run `floci az setup`.
- ### `floci az setup`
- `az group create`, `az login` and every other control-plane command go to public Azure
- unless the `az` CLI is told otherwise. `floci az setup` does it in one step:
- 1. fetches the emulator's CA certificate from `/_floci/tls-cert` and writes a CA bundle
- (the JDK's public roots plus that certificate);
- 2. registers (or updates) an az cloud named after the container (`floci-az` by default) whose ARM and Entra endpoints point at
- `https://localhost:<port>`, and makes it the active cloud;
- 3. turns off `core.instance_discovery`, which otherwise fails the login with `invalid_instance`;
- 4. logs in as a service principal with the dev identity (tenant
- `00000000-0000-0000-0000-000000000002`, subscription `00000000-0000-0000-0000-000000000001`).
- Everything is kept per instance, in `~/.floci/az/<container>/`, so instances started from
- different profiles never share a certificate, cloud or login (see
- [Running several instances side by side](#running-several-instances-side-by-side)). By default the
- az config itself is isolated there too and `~/.azure` is left untouched; `eval $(floci az env)`
- then points `az` at it in the current shell only. `--global` writes to your default az config
- instead, and removes that instance's earlier isolated config. Re-running is safe: the cloud is updated, not registered twice.
- The az CLI only logs in over HTTPS, so `floci az start` always starts Floci Azure with
- `FLOCI_AZ_TLS_ENABLED=true` (HTTP keeps working on the same port). A container started by an
- older floci has TLS off; run `floci az restart` once.
- ```sh
- floci az setup # isolated config under ~/.floci/az/floci-az
- eval $(floci az env) # AZURE_CONFIG_DIR + REQUESTS_CA_BUNDLE + connection string
- az group create -n my-rg -l westeurope
- floci az setup --profile team-b # a second instance: ~/.floci/az/<its container>
- eval $(floci az env --profile team-b)
- floci az setup --global # use your default az config (~/.azure)
- eval $(floci az env) # REQUESTS_CA_BUNDLE, and clears a stale AZURE_CONFIG_DIR
- floci az setup --reset # delete the isolated config
- floci az setup --reset --global # switch the default az config back to AzureCloud
- floci az setup -o json # structured output
- ```
- Requires the `az` CLI on your `PATH`. `--tenant`, `--subscription`, `--client-id` and
- `--client-secret` override the dev identity; Floci Azure never checks the secret.
- ### `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.
- ```sh
- 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.
- ```sh
- 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`
- ```sh
- 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`
- ```sh
- 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`
- ```sh
- floci doctor # run all checks
- floci doctor --check docker.installed # run a single check by name
- 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`
- ```sh
- floci version # CLI version, server version, image digest
- floci version -o json
- ```
- `floci version` and `floci status` warn on stderr when the AWS server is older than 1.5.0, the
- oldest version this CLI supports. The GCP, Azure and OCI emulators are versioned separately and
- have no minimum yet.
- ### `floci services` / `floci gcp services` / `floci az services` / `floci oci services`
- ```sh
- floci services # list all enabled services
- floci services -o json
- ```
- ### `floci reset` / `floci gcp reset` / `floci az reset` / `floci oci reset`
- ```sh
- floci reset # asks first, then deletes every resource; the emulator keeps running
- floci reset --yes # no prompt (required when not on a terminal, e.g. in CI)
- floci gcp reset -y -o json
- ```
- It calls the emulator's `POST <prefix>/state/reset`. The AWS, GCP and OCI emulators serve it; on a
- server without it (currently floci-az) the command says reset is not available and exits 1. Without
- `--yes` and with no terminal to ask on, it exits 2.
- Reset never guesses which server to wipe:
- - An `--endpoint` you type is used as given.
- - A container you select (`--container`, a profile's `container`, or `FLOCI_CONTAINER`) has to be
- running. If it is missing or stopped, nothing is reset.
- - An endpoint a profile or `FLOCI_ENDPOINT` supplies is used when no container is selected. A
- container that happens to run locally under the default name never takes its place.
- - When both a container and an endpoint are configured, they have to be the same server. If they
- are not, nothing is reset and you are asked to pass `--endpoint` or `--container`.
- - A container on a remote Docker host (`DOCKER_HOST=tcp://other-host:...` or `ssh://...`) is only
- reset through an endpoint, since its published port is not on this machine. A daemon on this
- machine reached over TCP (`tcp://127.0.0.1:2375`) is local.
- When reset refuses to choose a server, the command exits 1 without sending anything.
- ### `floci config`
- ```sh
- 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: container, port, data dir
- floci config profile create <name> # create a new profile with the tree's defaults
- floci config profile create <name> --container <c> --port <p> --persist <dir> --services <csv> --image <img> --namespace <ns>
- floci config profile show <name> # show a profile
- floci config profile show <name> --json # the same keys as one row of `config profile list --json`
- floci config profile edit <name> # open the profile in $VISUAL or $EDITOR, then check it still reads
- floci config profile delete <name> # delete a profile
- floci config validate -f docker-compose.yml # validate a Compose file
- ```
- Each product tree has its own `config show|validate|profile` (`floci gcp config show`, ...), which
- uses that product's defaults; `config default-product` is available through bare `floci config`
- and `floci aws config`, but not through the GCP, Azure, or OCI config trees.
- `config validate` reads the Compose file and checks the service that runs the emulator (found by
- its image; a file with a single service is checked whatever its image is):
- | Check | Result when it fails |
- |---|---|
- | The emulator port is mapped over TCP (`"4566:4566"`, `"5566:4566"`, `"127.0.0.1:5566:4566"`, a range, or the long form; any host port works) | error |
- | A socket is mounted at `/var/run/docker.sock` in the container (the host side may be any socket) | error where the product needs it, otherwise a warning |
- | The volume at `/app/data` is writable and not bound to a file | error |
- | A volume at `/app/data` comes with `<PREFIX>_STORAGE_MODE=persistent`, and the other way round | warning |
- | The image tag is not older than the oldest version this CLI supports (AWS tree) | warning |
- It exits 1 when there is an error and 0 otherwise. `-o json` and `-o yaml` print
- `file`, `service`, `valid`, `errors` and `warnings`, also for a file that cannot be parsed. An
- `env_file` is not read, so nothing is said about a storage mode it may set.
- #### Profiles
- Profiles are stored in `~/.floci/profiles/<name>.yaml`. Pass `--profile <name>` to any command to
- load one; `floci config profile create <name>` writes a starter file seeded with the defaults of
- the tree you run it under.
- ```yaml
- name: probe
- endpoint: http://localhost:4566
- container: floci-probe
- image: floci/floci:enforced
- port: 4599
- persistDir: /tmp/floci-persist
- services: s3,lambda
- namespace: team-probe
- output: json
- ```
- Each field supplies the default for one flag, so a profile field only affects the commands that
- have that flag:
- | Profile field | Flag it supplies | Used by |
- |---|---|---|
- | `endpoint` | `--endpoint` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
- | `container` | `--container` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
- | `output` | `--output` / `-o` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
- | `image` | `--image` | `start`; `restart` re-applies it through the start it runs |
- | `port` | `--port` | `start`; `restart` re-applies it through the start it runs |
- | `persistDir` | `--persist` | `start`; `restart` re-applies it through the start it runs |
- | `services` | `--services` | `start`; `restart` re-applies it through the start it runs |
- | `namespace` | `--namespace` | `start`; `restart` re-applies it through the start it runs |
- Resolution order, highest first:
- ```
- command-line flag > --profile <name> > FLOCI_* environment variable > built-in default
- ```
- So `floci start --profile probe --container other` starts `other`, and a profile beats a
- `FLOCI_CONTAINER` exported in your shell. A field the profile leaves out changes nothing.
- An unknown or unreadable profile is an error (exit 2), not a silent fall back to the defaults.
- That includes `floci config show --profile <name>`, which before 0.2.2 warned and showed the
- defaults instead.
- A key floci does not read (a typo such as `persist_dir:`) is ignored with a warning that lists
- the keys a profile can set.
- Values are interpolated by the CLI, so `persistDir: ${env:HOME}/floci-data` expands as you would
- expect.
- > Profiles are shared by all four product trees: there is one `~/.floci/profiles/` directory, not
- > one per product. A profile created under `floci gcp` carries GCP defaults, so passing it to the
- > AWS tree will start a GCP container; name them accordingly.
- > `floci restart --profile <name>` re-applies the profile's `persistDir`, so state survives the
- > restart. A plain `floci restart` has no `--persist` flag of its own and still falls back to the
- > defaults.
- #### Running several instances side by side
- An instance is a profile. Its **container name** is its identity, its **port** is the only thing
- that must differ from the other instances, and its **persist dir** keeps its state across
- container recreation. Hints for follow-up CLI commands preserve the selected profile, container
- and explicit endpoint, and a retried `start` keeps the flags you typed. Every command (`status`, `logs`, `env`, `doctor`, `stop`, ...) finds the
- instance through its container, so passing the same `--profile` is all it takes. Any local state
- the CLI keeps about an instance lives in `~/.floci/<product>/<container>/`.
- Each instance's emulator also gets its own Docker resource namespace, derived from the container
- name unless the profile sets `namespace`. That keeps the containers each instance launches (Lambda functions,
- ECS tasks, Cloud Run jobs, Service Bus sidecars, ...) apart, so starting one instance never
- cleans up another's. `floci config show --profile <name>` prints the namespace it will use.
- Leave `endpoint` at the product default: the CLI reads the real host port from the running
- container. `config profile create` warns when a new profile reuses another profile's container,
- or its port or resource namespace on the same image.
- ```sh
- # AWS
- floci config profile create aws-a --container floci-a --port 4566 --persist ~/.floci/data/aws-a
- floci config profile create aws-b --container floci-b --port 14566 --persist ~/.floci/data/aws-b
- floci start --profile aws-a && floci start --profile aws-b
- eval $(floci env --profile aws-b) # AWS_ENDPOINT_URL points at :14566
- # GCP
- floci gcp config profile create gcp-b --container floci-gcp-b --port 14588 --persist ~/.floci/data/gcp-b
- floci gcp start --profile gcp-b
- eval $(floci gcp env --profile gcp-b)
- # Azure: setup is per instance too (its own certificate, az cloud and login)
- floci az config profile create az-b --container floci-az-b --port 14577 --persist ~/.floci/data/az-b
- floci az start --profile az-b
- floci az setup --profile az-b
- eval $(floci az env --profile az-b) # plain az now talks to floci-az-b only
- # OCI: 'floci oci setup' is shared, the endpoint is per instance
- floci oci config profile create oci-b --container floci-oci-b --port 14599 --persist ~/.floci/data/oci-b
- floci oci start --profile oci-b
- eval $(floci oci env --profile oci-b)
- floci config profile list # one row per instance
- floci stop --profile aws-b # stop one, the others keep running
- ```
- Without `--persist` an instance starts empty each time its container is recreated. For floci-az
- it also gets a new certificate, which `floci az env` reports so you can re-run `floci az setup`.
- ### `floci snapshot`
- Save and restore named snapshots of Floci AWS state.
- ```sh
- floci snapshot list
- floci snapshot save <name>
- floci snapshot load <name>
- floci snapshot delete <name>
- floci snapshot export <name> -f tarball.tar.gz
- floci snapshot import -f 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 completion`
- ```sh
- floci completion bash >> ~/.bashrc
- floci completion zsh >> ~/.zshrc
- ```
- Completion scripts are generated for bash and zsh. Any other shell name is a usage error (exit 2).
- The zsh script loads the bash completion through `bashcompinit` and sets up `floci` only: your shell
- options and aliases are left as they were.
- ### `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.
- ```sh
- floci update # update to the latest release
- floci update --check # exit 0: up to date, 1: update available, 2: the check failed
- floci update --version 0.1.7 # install a specific version
- floci update --check || floci update # script-friendly: update only when stale
- ```
- 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.
- ---
- ## Exit Codes
- Every command in every tree (`floci`, `floci aws`, `floci gcp`, `floci az`, `floci oci`) follows
- the same three codes:
- | Code | Meaning |
- |---|---|
- | `0` | The command did what it was asked. |
- | `1` | It ran and failed, or the answer to the question it asks is "no". |
- | `2` | The command line could not be used: an unknown flag or command, a missing argument, a value picocli cannot convert (`--port abc`), or a `--profile` that does not exist or cannot be read. |
- A value the command line accepts but the command then rejects is exit `2` as well, in every
- command: an out-of-range `--port`, an unknown `--pull` policy, a `--persist` path that cannot be
- used, a `--version` that is not a release version, an unknown product or action, a missing or
- invalid name. Exit `1` always means the command ran.
- Where a command's codes carry a specific meaning a script can rely on:
- | Command | `0` | `1` | `2` |
- |---|---|---|---|
- | `status` | the instance is up | it is not: the server does not answer, or its container is stopped | bad flag or profile |
- | `wait` | ready before `--timeout` | timed out | `--timeout` is not a positive duration |
- | `doctor` | every check passed (warnings allowed) | at least one check failed | `--check` names no known check |
- | `update --check` | up to date | an update is available | the check itself failed |
- | `update` | updated, or already up to date | the update failed; the binary is unchanged | `--version` is not a release version |
- | `start`, `restart` | started (and ready, unless `--detach`) | Docker, the image, the port or readiness failed, or the `--persist` directory cannot be created | `--port`, `--pull`, the namespace, the `--persist` path or a `--security-opt seccomp=` value is not valid |
- | `stop` | stopped, or was not running | no such container, or Docker failed | bad flag or profile |
- | `reset` | state reset | declined, not available on this server, no running instance to reset, or the configuration names two different servers | no terminal to ask on and no `--yes` |
- | `config validate` | no errors (warnings allowed) | errors found, or the file cannot be read | bad flag |
- | `config profile ...` | done | not found, already exists, cannot be read, or (for `edit`) no editor is set, the editor failed or the file no longer parses | unknown action, missing or invalid profile name, `--port` out of range |
- | `config default-product` | saved | the file cannot be written | not `aws`, `gcp`, `az` or `oci` |
- | `env` | variables printed | the selected container has no known endpoint | `--shell` is not supported |
- | `completion` | script printed | | the shell is not `bash` or `zsh` |
- | `snapshot ...` | done | failed, or the server has no snapshot API yet | invalid snapshot name |
- `docs/help/` holds the `--help` text of every command, generated from the code. A test fails when
- the files and the commands drift apart; regenerate them with
- `mvn test -Dtest=HelpSnapshotTest -Dfloci.help.update=true`.
- ---
- ## CI Usage
- ### AWS CI
- ```sh
- floci start --detach
- floci wait --timeout 60s
- eval $(floci env)
- pytest # or your test command
- floci stop --remove
- ```
- With Docker Compose:
- ```yaml
- 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](#docker-daemon-resolution-podman-rootless-remote-contexts).
- ### GCP CI
- ```sh
- 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:
- ```yaml
- services:
- floci-gcp:
- image: floci/floci-gcp:latest
- ports:
- - "4588:4588"
- volumes:
- - /var/run/docker.sock:/var/run/docker.sock
- ```
- ### Azure CI
- ```sh
- 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:
- ```yaml
- services:
- floci-az:
- image: floci/floci-az:latest
- ports:
- - "4577:4577"
- volumes:
- - /var/run/docker.sock:/var/run/docker.sock
- ```
- ### OCI CI
- ```sh
- 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:
- ```yaml
- services:
- floci-oci:
- image: floci/floci-oci:latest
- ports:
- - "4599:4599"
- volumes:
- - /var/run/docker.sock:/var/run/docker.sock
- ```
- ---
- ## AI agents
- [`skills/floci/`](skills/floci/) is an [Agent Skill](https://agentskills.io) that teaches coding agents (Claude Code,
- Codex, Cursor, Kiro, Gemini CLI and others) to work with Floci: install and drive this CLI, wire `aws`, `gcloud`, `az`,
- `oci` and the SDKs to the emulators without touching real cloud, write `docker run` commands and Compose files, run
- several instances side by side, and look things up in the published documentation of each emulator
- ([AWS](https://floci.io/floci/), [Azure](https://floci.io/floci-az/), [GCP](https://floci.io/floci-gcp/),
- [OCI](https://floci.io/floci-oci/)) instead of guessing.
- ```sh
- # Any supported agent (asks which ones to install it for)
- npx skills add floci-io/floci-cli
- # Claude Code, as a plugin
- /plugin marketplace add floci-io/floci-cli
- /plugin install floci@floci
- ```
- In [Kiro](https://kiro.dev), install it as a power: Powers panel, **Add Custom Power**, **Import power from GitHub**,
- and enter `https://github.com/floci-io/floci-cli`. The `plugin.json` at the repository root is the
- [Agent Plugins](https://agent-plugins.org) manifest Kiro reads. Kiro also loads plain Agent Skills, so copying
- `skills/floci/` into `.kiro/skills/` (or `~/.kiro/skills/`) works as well.
- Or copy the `skills/floci/` directory into your agent's skills directory (for example `~/.claude/skills/floci/`).
- | Part | What it holds |
- |---|---|
- | `SKILL.md` | Lifecycle, safety rules (fake credentials only, verify the endpoint, explicit product tree) and when to read what |
- | `references/` | One page per cloud, plus Docker and Compose, multiple instances and namespaces, CI, troubleshooting, and how to find a page in the docs |
- | `assets/compose/` | Compose templates for each emulator and for all four together |
- | `scripts/` | `install-floci.sh` and `ensure-running.sh` (bash) |
- The skill follows the CLI: `SkillDocsTest` checks every `floci` command it quotes against the real command tree.
- ---
- ## 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.
- ---
- ## Testcontainers
- Running Floci in tests? Use the Testcontainers module for your language instead of scripting the CLI:
- | Language | Repository |
- |---|---|
- | Java | [testcontainers-floci](https://github.com/floci-io/testcontainers-floci) |
- | Node.js / TypeScript | [testcontainers-floci-node](https://github.com/floci-io/testcontainers-floci-node) |
- | Python | [testcontainers-floci-python](https://github.com/floci-io/testcontainers-floci-python) |
- | Go | [testcontainers-floci-go](https://github.com/floci-io/testcontainers-floci-go) |
- | .NET | [testcontainers-floci-dotnet](https://github.com/floci-io/testcontainers-floci-dotnet) |
- ## Community
- - 💬 [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw): quick questions and community chat
- - 🗣️ [GitHub Discussions](https://github.com/orgs/floci-io/discussions): ideas, design tradeoffs, and proposals
- - 🐛 [Issues](https://github.com/floci-io/floci-cli/issues): bugs in this CLI or in the agent skill (emulator bugs go to that emulator's repository)
- - 🛟 [SUPPORT.md](https://github.com/floci-io/.github/blob/main/SUPPORT.md): where to get help, and what community support covers
- - [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](https://github.com/floci-io/.github/blob/main/SECURITY.md) · [CODE_OF_CONDUCT.md](https://github.com/floci-io/.github/blob/main/CODE_OF_CONDUCT.md) · [MAINTAINERS.md](MAINTAINERS.md)
- ## Privacy
- The Floci CLI and the agent skill in [`skills/floci/`](skills/floci/) collect no data. There is no telemetry, no
- analytics, no account and no sign-in, and nothing you do with them is reported to the Floci project.
- The only network requests they make are the ones needed to do what you asked:
- | Request | To | When |
- |---|---|---|
- | Release check | `api.github.com` | At most once every 24 hours from an interactive terminal, and on `floci update`. Turn it off with `FLOCI_NO_UPDATE_CHECK=1`; it is off in CI and for piped output |
- | Binary download | `github.com` (release assets) | Only when you run `floci update` or the install script |
- | Image pull | Your container registry (Docker Hub by default) | When `docker` pulls an emulator image on `floci start` |
- | Name lookup | DNS for `localhost.floci.io`, which answers `127.0.0.1` | When a tool uses the endpoint that `floci env` prints for AWS |
- | Documentation pages | `floci.io` and `raw.githubusercontent.com` | When an agent using the skill looks something up |
- Those services see what any HTTP or DNS request shows them (such as your IP address) and apply their own privacy
- policies. Everything else stays on your machine: the emulators run locally, your cloud CLIs and SDKs talk to
- `localhost`, and profiles and state live under `~/.floci`. The skill tells agents to use only the fake credentials the
- emulators accept and never to read or reuse real cloud credentials.
- Questions about this: see [Community](#community).
- ## License
- MIT. See [LICENSE](LICENSE).
- ---
- <div align="center">
- Floci™ is a trademark of Hector Ventura. Code is MIT-licensed; see
- [TRADEMARK.md](https://github.com/floci-io/.github/blob/main/TRADEMARK.md) for name and logo use.
- </div>
installer/install.ps1 · Bundled script · 56 lines · 1 finding marked
- # Floci CLI Windows installer
- # Usage: iwr https://floci.io/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 2 on GitHub
- [CmdletBinding()]
- param(
- [string]$Version = "latest",
- [string]$InstallDir = "$env:LOCALAPPDATA\floci\bin"
- )
- $ErrorActionPreference = "Stop"
- $Repo = "floci-io/floci-cli"
- function Get-LatestVersion {
- $response = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest"
- return $response.tag_name
- }
- function Main {
- Write-Host "Installing Floci CLI..." -ForegroundColor Cyan
- if ($Version -eq "latest") {
- $Version = Get-LatestVersion
- }
- $Arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
- $Platform = "windows-$Arch"
- $FileName = "floci-$Platform.exe"
- $DownloadUrl = "https://github.com/$Repo/releases/download/$Version/$FileName"
- Write-Host "Downloading floci $Version for $Platform..."
- if (-not (Test-Path $InstallDir)) {
- New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
- }
- $Destination = Join-Path $InstallDir "floci.exe"
- Invoke-WebRequest -Uri $DownloadUrl -OutFile $Destination -UseBasicParsing
- # Add to PATH if not already there
- $CurrentPath = [Environment]::GetEnvironmentVariable("Path", "User")
- if ($CurrentPath -notlike "*$InstallDir*") {
- [Environment]::SetEnvironmentVariable("Path", "$CurrentPath;$InstallDir", "User")
- Write-Host "Added $InstallDir to user PATH (restart your terminal)"
- }
- Write-Host ""
- Write-Host "Floci CLI $Version installed to $Destination" -ForegroundColor Green
- Write-Host ""
- Write-Host "Quick start:"
- Write-Host " floci start"
- Write-Host " floci doctor"
- Write-Host ' $env:AWS_ENDPOINT_URL="http://localhost:4566"'
- Write-Host " aws s3 mb s3://my-bucket"
- }
- Main
installer/install.sh · Bundled script · 142 lines · 1 finding marked
- #!/usr/bin/env sh
- # Floci CLI installer — curl -fsSL https://floci.io/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 2 on GitHub
- set -e
- VERSION="${FLOCI_CLI_VERSION:-latest}"
- INSTALL_DIR="${FLOCI_INSTALL_DIR:-/usr/local/bin}"
- BINARY="floci"
- REPO="floci-io/floci-cli"
- SKIP_CHECKSUM="${FLOCI_SKIP_CHECKSUM:-0}"
- DOWNLOAD_RETRIES="${FLOCI_DOWNLOAD_RETRIES:-4}"
- # Download $1 to $2, retrying on transient failures. GitHub's CDN intermittently
- # returns 5xx (e.g. 504) on release assets, and can hand back a 0-byte body, so
- # we wrap curl in our own loop with backoff: an empty file is treated as a
- # failure and retried. curl's own --retry handles mid-transfer hiccups; the
- # outer loop covers cases it doesn't and works uniformly across curl versions.
- download() {
- _url="$1"
- _out="$2"
- _attempt=1
- while :; do
- if curl -fsSL --retry 2 --retry-delay 1 "$_url" -o "$_out" && [ -s "$_out" ]; then
- return 0
- fi
- if [ "$_attempt" -ge "$DOWNLOAD_RETRIES" ]; then
- return 1
- fi
- _delay=$((_attempt * 2))
- echo " download failed (attempt ${_attempt}/${DOWNLOAD_RETRIES}), retrying in ${_delay}s..." >&2
- sleep "$_delay"
- _attempt=$((_attempt + 1))
- done
- }
- detect_platform() {
- OS=$(uname -s | tr '[:upper:]' '[:lower:]')
- ARCH=$(uname -m)
- case "$ARCH" in
- x86_64) ARCH="amd64" ;;
- aarch64|arm64) ARCH="arm64" ;;
- *) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
- esac
- case "$OS" in
- linux) PLATFORM="linux-${ARCH}" ;;
- darwin) PLATFORM="darwin-${ARCH}" ;;
- *) echo "Unsupported OS: $OS" >&2; exit 1 ;;
- esac
- echo "$PLATFORM"
- }
- fetch_latest_version() {
- _tmp=$(mktemp)
- if ! download "https://api.github.com/repos/${REPO}/releases/latest" "$_tmp"; then
- rm -f "$_tmp"
- echo "Error: could not reach GitHub to determine the latest version." >&2
- echo "Check your connection, or pin a version with FLOCI_CLI_VERSION=<tag>." >&2
- exit 1
- fi
- _version=$(grep '"tag_name"' "$_tmp" | sed 's/.*"tag_name": "\(.*\)".*/\1/')
- rm -f "$_tmp"
- if [ -z "$_version" ]; then
- echo "Error: could not parse the latest version from the GitHub API response." >&2
- exit 1
- fi
- echo "$_version"
- }
- main() {
- echo "Installing Floci CLI..."
- PLATFORM=$(detect_platform)
- if [ "$VERSION" = "latest" ]; then
- VERSION=$(fetch_latest_version)
- fi
- DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${VERSION}/floci-${PLATFORM}"
- TMP=$(mktemp)
- echo "Downloading floci ${VERSION} for ${PLATFORM}..."
- if ! download "$DOWNLOAD_URL" "$TMP"; then
- rm -f "$TMP"
- echo "Error: failed to download the Floci binary from:" >&2
- echo " $DOWNLOAD_URL" >&2
- echo "GitHub may be returning a temporary error (e.g. HTTP 504). Please retry shortly." >&2
- exit 1
- fi
- chmod +x "$TMP"
- # Verify checksum if sha256sum is available
- if [ "$SKIP_CHECKSUM" != "1" ] && command -v sha256sum >/dev/null 2>&1; then
- SUMS_URL="https://github.com/${REPO}/releases/download/${VERSION}/sha256sums.txt"
- SUMS_TMP=$(mktemp)
- # Fetch to a file so a failed download is caught here, not silently
- # swallowed inside a pipeline (which would yield an empty expected sum
- # and a misleading "checksum mismatch").
- if ! download "$SUMS_URL" "$SUMS_TMP"; then
- rm -f "$TMP" "$SUMS_TMP"
- echo "Error: failed to download checksums from:" >&2
- echo " $SUMS_URL" >&2
- echo "Cannot verify the binary's integrity. Please retry, or set" >&2
- echo "FLOCI_SKIP_CHECKSUM=1 to install without verification." >&2
- exit 1
- fi
- EXPECTED=$(grep "floci-${PLATFORM}\$" "$SUMS_TMP" | awk '{print $1}')
- rm -f "$SUMS_TMP"
- if [ -z "$EXPECTED" ]; then
- rm -f "$TMP"
- echo "Error: no checksum entry for floci-${PLATFORM} in sha256sums.txt." >&2
- echo "Please report this at https://github.com/${REPO}/issues." >&2
- exit 1
- fi
- ACTUAL=$(sha256sum "$TMP" | awk '{print $1}')
- if [ "$EXPECTED" != "$ACTUAL" ]; then
- rm -f "$TMP"
- echo "Checksum mismatch for floci-${PLATFORM} — the download may be corrupted." >&2
- echo " expected: $EXPECTED" >&2
- echo " actual: $ACTUAL" >&2
- echo "Please retry the install." >&2
- exit 1
- fi
- echo "Checksum verified."
- fi
- # Install
- if [ -w "$INSTALL_DIR" ]; then
- mv "$TMP" "${INSTALL_DIR}/${BINARY}"
- else
- echo "Installing to ${INSTALL_DIR} requires sudo..."
- sudo mv "$TMP" "${INSTALL_DIR}/${BINARY}"
- fi
- echo ""
- echo "Floci CLI ${VERSION} installed to ${INSTALL_DIR}/${BINARY}"
- echo ""
- echo "Quick start:"
- echo " floci start # launch Floci"
- echo " floci doctor # check your environment"
- echo " export AWS_ENDPOINT_URL=http://localhost:4566"
- echo " aws s3 mb s3://my-bucket # use the AWS CLI against Floci"
- }
- main "$@"
skills/floci/scripts/install-floci.sh · Bundled script · 86 lines · 2 findings marked
- #!/usr/bin/env bash
- # Install floci-cli if it is missing. Linux and macOS.
- # Windows: iwr https://floci.io/install.ps1 | iex (installs to %LOCALAPPDATA%\floci\bin, no admin)
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 3 on GitHub
- #
- # Usage: install-floci.sh [--method brew|script] [--version <tag>] (tags have no 'v': 0.4.0)
- #
- # Defaults: Homebrew when brew is on PATH, otherwise the official install script into
- # ~/.local/bin, which needs no sudo (the script's own default, /usr/local/bin, prompts for
- # sudo, which hangs a non-interactive agent). Override the dir with FLOCI_INSTALL_DIR.
- set -euo pipefail
- method=""
- version="${FLOCI_CLI_VERSION:-latest}"
- while [[ $# -gt 0 ]]; do
- case "$1" in
- --method) method="${2:-}"; shift 2 ;;
- --version) version="${2:-}"; shift 2 ;;
- -h|--help) sed -n '2,10p' "$0"; exit 0 ;;
- *) echo "unknown argument: $1" >&2; exit 64 ;;
- esac
- done
- if command -v floci >/dev/null 2>&1; then
- echo "floci already installed: $(command -v floci)"
- floci version 2>/dev/null | head -1 || true
- if [[ "$version" != "latest" ]]; then
- echo "NOTE: --version $version was not applied. Use 'floci update --version $version' (or brew) to change the installed version." >&2
- fi
- exit 0
- fi
- case "$(uname -s)" in
- Linux|Darwin) ;;
- *) echo "Unsupported OS for this script. On Windows run: iwr https://floci.io/install.ps1 | iex" >&2; exit 1 ;;
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 34 on GitHub
- esac
- if [[ -z "$method" ]]; then
- if command -v brew >/dev/null 2>&1 && [[ "$version" == "latest" ]]; then
- method="brew"
- else
- method="script"
- fi
- fi
- case "$method" in
- brew)
- command -v brew >/dev/null 2>&1 || { echo "brew not found; use --method script" >&2; exit 1; }
- if [[ "$version" != "latest" ]]; then
- echo "NOTE: Homebrew installs the current release; --version $version is ignored. Use --method script to pin." >&2
- fi
- brew install floci-io/floci/floci
- ;;
- script)
- command -v curl >/dev/null 2>&1 || { echo "curl is required" >&2; exit 1; }
- dir="${FLOCI_INSTALL_DIR:-$HOME/.local/bin}"
- mkdir -p "$dir"
- tmp="$(mktemp)"
- trap 'rm -f "$tmp"' EXIT
- curl -fsSL https://floci.io/install.sh -o "$tmp"
- FLOCI_INSTALL_DIR="$dir" FLOCI_CLI_VERSION="$version" sh "$tmp"
- case ":$PATH:" in
- *":$dir:"*) ;;
- *)
- echo
- echo "NOTE: $dir is not on PATH. For this shell: export PATH=\"$dir:\$PATH\""
- echo "To make it permanent, add that line to ~/.bashrc or ~/.zshrc (ask the user first)."
- export PATH="$dir:$PATH"
- ;;
- esac
- ;;
- *)
- echo "unknown method: $method (use brew or script)" >&2; exit 64 ;;
- esac
- if ! command -v floci >/dev/null 2>&1; then
- echo "install finished but floci is not on PATH" >&2
- exit 1
- fi
- floci version 2>/dev/null | head -1 || true
- # The emulators run as containers; warn early if there is no Docker-compatible runtime.
- if ! command -v docker >/dev/null 2>&1; then
- echo "WARNING: docker CLI not found. Floci needs Docker (or Podman via DOCKER_HOST) to run the emulators." >&2
- elif ! docker info >/dev/null 2>&1; then
- echo "WARNING: docker is installed but the daemon is not reachable. Start Docker, or set DOCKER_HOST for Podman." >&2
- fi
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.