Skip to content
Back to search

floci

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/floci-io--floci-cli/badge.svg)](/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
  1. {
  2. "name": "floci",
  3. "owner": {
  4. "name": "Floci",
  5. "url": "https://floci.io"
  6. },
  7. "metadata": {
  8. "description": "Agent skills for Floci, the free local emulators for AWS, GCP, Azure and OCI"
  9. },
  10. "plugins": [
  11. {
  12. "name": "floci",
  13. "description": "Run, wire up and troubleshoot the Floci local cloud emulators with floci-cli, docker run or Docker Compose",
  14. "source": "./",
  15. "strict": false,
  16. "skills": [
  17. "./skills/floci"
  18. ]
  19. }
  20. ]
  21. }
README.md · README · 1,219 lines · 2 findings marked
  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/floci-io/.github/main/floci.svg#gh-light-mode-only" alt="Floci" width="500" />
  3. <img src="https://github.com/user-attachments/assets/edfff8b3-926c-471e-9549-77fb90a21b49#gh-dark-mode-only" alt="Floci" width="500" />
  4. </p>
  5. <p align="center">
  6. <strong>Any Cloud. Locally.</strong><br />
  7. Light, fluffy, and always free: the Floci command-line interface<br />
  8. No account. No auth token. No feature gates.
  9. </p>
  10. <p align="center">
  11. <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>
  12. <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>
  13. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
  14. <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>
  15. </p>
  16. <p align="center">
  17. <a href="#installation">Install</a> ·
  18. <a href="#quick-start">Quick Start</a> ·
  19. <a href="#command-reference">Commands</a> ·
  20. <a href="#the-floci-emulators">Emulators</a> ·
  21. <a href="https://floci.io">Docs</a>
  22. </p>
  23. ---
  24. ## What is this?
  25. `floci-cli` is the official command-line interface for [Floci](https://github.com/floci-io), the free, open-source
  26. local cloud emulators. It starts, stops, configures and diagnoses the emulator containers, and prints the
  27. environment your cloud CLI or SDK needs to talk to them. It does not manage cloud resources itself; your usual
  28. `aws`, `gcloud`, `az` and `oci` tools do that against the emulator (see [Scope](#scope)).
  29. ```sh
  30. # AWS (default)
  31. floci start
  32. eval $(floci env)
  33. aws s3 mb s3://my-bucket
  34. # GCP
  35. floci gcp start
  36. eval $(floci gcp env)
  37. gcloud storage buckets create gs://my-bucket
  38. # Azure
  39. floci az start
  40. floci az setup
  41. eval $(floci az env)
  42. az storage container create --name mycontainer
  43. az group create -n my-rg -l westeurope
  44. # OCI
  45. floci oci start
  46. floci oci setup
  47. eval $(floci oci env)
  48. oci os ns get
  49. ```
  50. ### The Floci emulators
  51. floci-cli drives every member of the [Floci](https://github.com/floci-io) emulator family. Floci is named after
  52. [floccus](https://en.wikipedia.org/wiki/Cirrocumulus_floccus), the cloud formation that looks like popcorn.
  53. | Emulator | Cloud | Port | CLI tree |
  54. |----------------------------------------------------|-------|:----:|----------------------------------|
  55. | [floci](https://github.com/floci-io/floci) | AWS | 4566 | `floci` / `floci aws` (default) |
  56. | [floci-az](https://github.com/floci-io/floci-az) | Azure | 4577 | `floci az` |
  57. | [floci-gcp](https://github.com/floci-io/floci-gcp) | GCP | 4588 | `floci gcp` |
  58. | [floci-oci](https://github.com/floci-io/floci-oci) | OCI | 4599 | `floci oci` |
  59. ## Installation
  60. ### Homebrew (macOS / Linux)
  61. ```sh
  62. brew install floci-io/floci/floci
  63. ```
  64. ### Install script (Linux / macOS)
  65. ```sh
  66. 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
  67. ```
  68. ### Windows (PowerShell)
  69. ```powershell
  70. iwr https://floci.io/install.ps1 | iex
  71. ```
  72. ### JVM fallback
  73. Download `floci.jar` from the [latest release](https://github.com/floci-io/floci-cli/releases/latest) and run it (requires **Java 25+**):
  74. ```sh
  75. java -jar floci.jar version
  76. ```
  77. ### Staying up to date
  78. Native-binary installs (install script, direct download) can self-update:
  79. ```sh
  80. floci update --check # exit 0: up to date, 1: update available, 2: the check failed
  81. floci update # download, verify checksum, replace the binary
  82. ```
  83. Homebrew installs are updated through Homebrew (`brew upgrade floci`); `floci update` detects Homebrew-managed binaries and refuses to touch them.
  84. ---
  85. ## Quick Start
  86. ### AWS
  87. ```sh
  88. # Start Floci (AWS emulator)
  89. floci start
  90. # Check environment
  91. floci doctor
  92. # Export AWS environment variables
  93. eval $(floci env)
  94. # Use AWS services normally
  95. aws s3 mb s3://my-bucket
  96. aws dynamodb create-table --table-name users \
  97. --attribute-definitions AttributeName=id,AttributeType=S \
  98. --key-schema AttributeName=id,KeyType=HASH \
  99. --billing-mode PAY_PER_REQUEST
  100. # Stop Floci
  101. floci stop
  102. ```
  103. ### GCP
  104. ```sh
  105. # Start Floci GCP emulator
  106. floci gcp start
  107. # Check environment
  108. floci gcp doctor
  109. # Export GCP emulator host variables
  110. eval $(floci gcp env)
  111. # Use GCP services normally
  112. gcloud storage buckets create gs://my-bucket
  113. gcloud pubsub topics create my-topic
  114. # Stop Floci GCP
  115. floci gcp stop
  116. ```
  117. ### Azure
  118. ```sh
  119. # Start Floci Azure emulator
  120. floci az start
  121. # Check environment
  122. floci az doctor
  123. # Point the az CLI at the emulator (certificate, cloud, login)
  124. floci az setup
  125. # Export the connection string and the az CLI config
  126. eval $(floci az env)
  127. # Use Azure services
  128. az storage container create --name mycontainer
  129. az storage blob upload --container-name mycontainer --name hello.txt --data "hello"
  130. az group create -n my-rg -l westeurope
  131. # Stop Floci Azure
  132. floci az stop
  133. ```
  134. ### OCI
  135. ```sh
  136. # Start Floci OCI emulator
  137. floci oci start
  138. # Check environment
  139. floci oci doctor
  140. # One-time: create a throwaway OCI CLI profile (API key + ~/.oci/config)
  141. floci oci setup
  142. # Export OCI endpoint variables
  143. eval $(floci oci env)
  144. # Use OCI services normally
  145. oci os ns get
  146. oci os bucket create --namespace-name floci-local --name my-bucket \
  147. --compartment-id ocid1.tenancy.oc1..flocilocaltenancy0000000000000000000000000000000000000000
  148. # Stop Floci OCI
  149. floci oci stop
  150. ```
  151. ### Switch default product
  152. Bare commands like `floci start` route to the configured default product (AWS by default).
  153. ```sh
  154. floci config default-product gcp # make floci gcp the default
  155. floci config default-product az # make floci az the default
  156. floci config default-product oci # make floci oci the default
  157. floci config default-product aws # revert to aws
  158. ```
  159. ---
  160. ## Command Reference
  161. 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.
  162. ### Shared commands (product-independent)
  163. | Command | Description |
  164. |---------|-------------|
  165. | `floci config default-product` | Set the default product (aws, gcp, az, or oci) |
  166. | `floci update` | Self-update the CLI to the latest release |
  167. | `floci completion bash\|zsh` | Generate shell completion scripts |
  168. ### AWS commands (`floci` / `floci aws`)
  169. | Command | Description |
  170. |---------|-------------|
  171. | `floci start` | Launch the Floci AWS container |
  172. | `floci stop` | Stop (and optionally remove) the container |
  173. | `floci restart` | Stop then start |
  174. | `floci status` | Show container state and server health |
  175. | `floci logs` | Stream container logs |
  176. | `floci wait` | Poll until Floci is ready (CI-friendly) |
  177. | `floci version` | Show CLI and server versions |
  178. | `floci services` | List enabled AWS services |
  179. | `floci reset` | Delete every resource in the running emulator, keeping it running |
  180. | `floci doctor` | Run environment diagnostics |
  181. | `floci env` | Print AWS environment variables |
  182. | `floci snapshot save/load/list/delete` | Manage state snapshots |
  183. | `floci config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (AWS defaults) |
  184. Bare `floci config ...` always means the AWS tree, whatever the default product; use
  185. `floci gcp config ...` and so on for the others.
  186. ### GCP commands (`floci gcp`)
  187. | Command | Description |
  188. |---------|-------------|
  189. | `floci gcp start` | Launch the Floci GCP container |
  190. | `floci gcp stop` | Stop (and optionally remove) the container |
  191. | `floci gcp restart` | Stop then start |
  192. | `floci gcp status` | Show container state and server health |
  193. | `floci gcp logs` | Stream container logs |
  194. | `floci gcp wait` | Poll until Floci GCP is ready (CI-friendly) |
  195. | `floci gcp version` | Show CLI and server versions |
  196. | `floci gcp services` | List enabled GCP services |
  197. | `floci gcp reset` | Delete every resource in the running emulator, keeping it running |
  198. | `floci gcp doctor` | Run GCP environment diagnostics |
  199. | `floci gcp env` | Print GCP SDK emulator host variables |
  200. | `floci gcp snapshot` | Snapshot commands (coming soon) |
  201. | `floci gcp config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (GCP defaults) |
  202. ### Azure commands (`floci az`)
  203. | Command | Description |
  204. |---------|-------------|
  205. | `floci az start` | Launch the Floci Azure container |
  206. | `floci az stop` | Stop (and optionally remove) the container |
  207. | `floci az restart` | Stop then start |
  208. | `floci az status` | Show container state and server health |
  209. | `floci az logs` | Stream container logs |
  210. | `floci az wait` | Poll until Floci Azure is ready (CI-friendly) |
  211. | `floci az version` | Show CLI and server versions |
  212. | `floci az services` | List enabled Azure services |
  213. | `floci az reset` | Delete every resource in the running emulator, keeping it running |
  214. | `floci az doctor` | Run Azure environment diagnostics |
  215. | `floci az env` | Print Azure connection string / SDK env vars |
  216. | `floci az setup` | Point the `az` CLI at the emulator: trust its certificate, register the cloud, log in |
  217. | `floci az snapshot` | Snapshot commands (coming soon) |
  218. | `floci az config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (Azure defaults) |
  219. ### OCI commands (`floci oci`)
  220. | Command | Description |
  221. |---------|-------------|
  222. | `floci oci start` | Launch the Floci OCI container |
  223. | `floci oci stop` | Stop (and optionally remove) the container |
  224. | `floci oci restart` | Stop then start |
  225. | `floci oci status` | Show container state and server health |
  226. | `floci oci logs` | Stream container logs |
  227. | `floci oci wait` | Poll until Floci OCI is ready (CI-friendly) |
  228. | `floci oci version` | Show CLI and server versions |
  229. | `floci oci services` | List enabled OCI services |
  230. | `floci oci reset` | Delete every resource in the running emulator, keeping it running |
  231. | `floci oci doctor` | Run OCI environment diagnostics |
  232. | `floci oci env` | Print OCI endpoint variables |
  233. | `floci oci setup` | Create a local OCI CLI profile (API key + `~/.oci/config`) |
  234. | `floci oci snapshot` | Snapshot commands (coming soon) |
  235. | `floci oci config show\|validate\|profile` | Show the active configuration, validate a docker-compose.yml, manage profiles (OCI defaults) |
  236. All commands support `--help`.
  237. ---
  238. ## Global Flags
  239. Every tree takes the same flags; only the defaults differ. With `--json` (or `-o json`, `-o yaml`)
  240. a command prints one document on stdout and nothing else. When a command cannot do what it was
  241. asked, the error is on stderr and stdout is empty. Exit `1` does not always mean that, though:
  242. `doctor`, `status` and `config validate` answer a question, and `start` and `restart` report on a
  243. container they did create, so each still prints its document when the answer is "no" (a failed
  244. check, an instance that is down, a file with errors, a start that never became ready). `wait`
  245. prints nothing when it times out. Read the exit code first, then the document.
  246. Two commands print text whatever the format, because their output is not a document: `logs` (the
  247. container's own output) and `completion` (a script). `env` prints shell
  248. code in text mode and the variables as a map in JSON or YAML. Marks are plain ASCII without
  249. `--no-emoji` too whenever the output is not a terminal (a pipe, a file, CI logs) or `NO_COLOR` is
  250. set. `--json` wins when it is combined with `--output`.
  251. ### AWS global flags
  252. ```
  253. --endpoint <url> Floci server URL (default: http://localhost:4566, env: FLOCI_ENDPOINT)
  254. --container <name> Container name (default: floci, env: FLOCI_CONTAINER)
  255. --output|-o text|json|yaml Output format (default: text)
  256. --json Shorthand for --output json
  257. --quiet, -q Suppress non-error output
  258. --verbose, -v Debug logging to stderr
  259. --no-color Disable ANSI colors
  260. --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
  261. --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
  262. ```
  263. Explicit flags override the profile; the profile overrides the environment variables.
  264. ### GCP global flags
  265. ```
  266. --endpoint <url> Floci GCP server URL (default: http://localhost:4588, env: FLOCI_GCP_ENDPOINT)
  267. --container <name> Container name (default: floci-gcp, env: FLOCI_GCP_CONTAINER)
  268. --output|-o text|json|yaml Output format (default: text)
  269. --json Shorthand for --output json
  270. --quiet, -q Suppress non-error output
  271. --verbose, -v Debug logging to stderr
  272. --no-color Disable ANSI colors
  273. --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
  274. --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
  275. ```
  276. Explicit flags override the profile; the profile overrides the environment variables.
  277. ### Azure global flags
  278. ```
  279. --endpoint <url> Floci Azure server URL (default: http://localhost:4577, env: FLOCI_AZ_ENDPOINT)
  280. --container <name> Container name (default: floci-az, env: FLOCI_AZ_CONTAINER)
  281. --output|-o text|json|yaml Output format (default: text)
  282. --json Shorthand for --output json
  283. --quiet, -q Suppress non-error output
  284. --verbose, -v Debug logging to stderr
  285. --no-color Disable ANSI colors
  286. --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
  287. --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
  288. ```
  289. Explicit flags override the profile; the profile overrides the environment variables.
  290. ### OCI global flags
  291. ```
  292. --endpoint <url> Floci OCI server URL (default: http://localhost:4599, env: FLOCI_OCI_ENDPOINT)
  293. --container <name> Container name (default: floci-oci, env: FLOCI_OCI_CONTAINER)
  294. --output|-o text|json|yaml Output format (default: text)
  295. --json Shorthand for --output json
  296. --quiet, -q Suppress non-error output
  297. --verbose, -v Debug logging to stderr
  298. --no-color Disable ANSI colors
  299. --no-emoji Plain ASCII marks (+ ! x ->) instead of Unicode ones
  300. --profile <name> Load settings from ~/.floci/profiles/<name>.yaml
  301. ```
  302. Explicit flags override the profile; the profile overrides the environment variables.
  303. > **Port auto-detection:** `status`, `version`, `wait`, and `env` automatically derive the correct
  304. > endpoint from the container's port mapping. You don't need to pass `--endpoint` when using
  305. > a non-default port, as long as `--container` points to the right container.
  306. ---
  307. ## Commands
  308. ### `floci start` / `floci gcp start` / `floci az start` / `floci oci start`
  309. Pulls the image (if needed), starts the container, and waits for readiness.
  310. ```sh
  311. # AWS
  312. floci start # default port 4566
  313. floci start --port 4567 # custom host port
  314. floci start --services s3,dynamodb # enable specific services
  315. floci start --persist ./data # persist state to a host directory
  316. floci start --pull always # always pull the latest image
  317. floci start --detach # return immediately, don't wait
  318. floci start --namespace team-b # scope the containers it launches (see below)
  319. # GCP
  320. floci gcp start # default port 4588
  321. floci gcp start --persist ./data # persist state to a host directory
  322. floci gcp start --namespace team-b # scope the containers it launches
  323. # Azure
  324. floci az start # default port 4577
  325. floci az start --port 4578 # custom host port
  326. floci az start --persist ./data # persist state to a host directory
  327. floci az start --namespace team-b # scope the containers it launches
  328. # OCI
  329. floci oci start # default port 4599
  330. floci oci start --persist ./data # persist state to a host directory
  331. floci oci start --namespace team-b # scope the containers it launches
  332. ```
  333. `--namespace` sets the emulator's Docker resource namespace (`FLOCI_DOCKER_RESOURCE_NAMESPACE`,
  334. `FLOCI_GCP_…`, `FLOCI_AZ_…`, `FLOCI_OCI_…`). The emulator puts it in the names and the
  335. `floci_namespace` label of the containers and volumes it launches (Lambda, ECS, RDS, Cloud Run,
  336. Service Bus, ...) and only cleans up leftovers in its own namespace. When `--container` is not the
  337. product default, the namespace is derived from it, without the default-container prefix the
  338. emulator already adds (`floci-gcp-b` → `b`, so children are `floci-gcp-b-…`; `team-b` stays
  339. `team-b`). The default container gets none.
  340. On a `--port` other than the product default, `start` also sets the emulator's base URL
  341. (`FLOCI_BASE_URL`, `FLOCI_GCP_BASE_URL`, ...) to the endpoint with that port (`http://localhost:<port>`
  342. unless `--endpoint` names another host), so URLs it returns
  343. (SQS `QueueUrl`, presigned URLs, the OCI functions invoke endpoint) point at that instance.
  344. #### Docker daemon resolution (Podman, rootless, remote contexts)
  345. The Floci container needs access to a Docker-compatible daemon (for Lambda, EC2,
  346. EKS, MSK, ECR, CodeBuild, and Kafka/Redpanda support). By default `floci start`
  347. bind-mounts `/var/run/docker.sock`, but it honors the standard `DOCKER_HOST`
  348. environment variable, so Podman, rootless setups, and remote Docker contexts work
  349. without extra flags:
  350. ```sh
  351. # Rootless Podman
  352. export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
  353. floci start
  354. # Rootful Podman
  355. export DOCKER_HOST=unix:///run/podman/podman.sock
  356. floci start
  357. # Remote daemon over TCP
  358. export DOCKER_HOST=tcp://10.0.0.5:2375
  359. floci start
  360. ```
  361. Resolution precedence:
  362. 1. **`DOCKER_HOST`**: the standard Docker/Podman variable (`unix://` socket, `tcp://` daemon, or `npipe://` on Windows)
  363. 2. **`DOCKER_SOCK`**: legacy override (a bare socket path)
  364. 3. **OS default**: `/var/run/docker.sock` on Linux/macOS, or the Docker named pipe on Windows
  365. For a `unix://` socket the resolved path is bind-mounted into the container; for a
  366. remote `tcp://` daemon the `DOCKER_HOST` value is passed through to the container
  367. instead. Run `floci doctor` to see which endpoint was resolved.
  368. With `podman machine` on macOS, the socket on the Mac (the one `podman machine start` prints) is
  369. a forwarder, and the container runs inside the VM, where that path is not the daemon's socket.
  370. When the daemon is Podman, `floci start` asks `podman info` for the socket the daemon listens on
  371. inside the VM (`/run/podman/podman.sock` rootful, `/run/user/<uid>/podman/podman.sock` rootless)
  372. and mounts that instead, so this needs the `podman` CLI on `PATH`. Set `DOCKER_SOCK` to choose
  373. the mounted socket yourself: on macOS it is the mount even when `DOCKER_HOST` is set, and podman
  374. is not asked.
  375. With SELinux enforcing (for example the Fedora VM behind `podman machine`), the container's label
  376. keeps Floci from connecting to the socket, and the web console fails to start with
  377. `java.net.BindException: Permission denied`. Relabeling the mount with `:z` is not enough: it fixes
  378. access to the socket file, but SELinux also checks the daemon on the other end of the socket. Turn
  379. labeling off for the Floci container instead:
  380. ```sh
  381. floci start --security-opt label=disable
  382. ```
  383. `--security-opt` is passed to `docker run` unchanged and can be repeated. Without `--profile`,
  384. `floci restart` passes back the options `docker inspect` reports for the running container. With
  385. `--profile` it starts from the profile, which has no key for them: run
  386. `floci <product> stop --profile <name> --remove`, then
  387. `floci <product> start --profile <name> --security-opt ...`, where `<product>` is the profile's
  388. `aws`, `gcp`, `az` or `oci`.
  389. ### `floci stop` / `floci gcp stop` / `floci az stop` / `floci oci stop`
  390. ```sh
  391. floci stop # graceful stop (10s timeout)
  392. floci stop --timeout 30 # wait up to 30s before force-kill
  393. floci stop --timeout -1 # never force-kill: wait for the container to exit
  394. floci stop --remove # also remove the container after stopping
  395. floci stop -o json # {"container", "state", "stopped", "removed"}
  396. ```
  397. `start`, `stop` and `restart` print one document with `-o json` or `-o yaml` and nothing else on
  398. stdout: the progress lines are left out and docker's pull progress goes to stderr. `start` and
  399. `restart` report `container`, `id`, `image`, `endpoint`, `state` and `ready` (`ready` is absent
  400. with `--detach`). `logs` prints the container's own output and stays plain text.
  401. If `restart` fails after removing the old container, stderr includes a `start` command with
  402. the resolved container, port, image, endpoint, persistence, services and namespace settings.
  403. It also appears with structured output. Review the failure, then run that command to retry. If
  404. the new container is running but did not become ready, stderr instead says to check `logs` and
  405. run `wait`, because `start` refuses a running container.
  406. A selected container with no published port and no configured endpoint has no known endpoint.
  407. `status` does not probe the default instance and reports `endpoint: null` in structured output.
  408. `env`, `services`, `az setup` and the `snapshot` commands exit `1` with the next step rather than
  409. act on the default instance. `doctor` and `version` still run and do not probe it. `wait` keeps
  410. looking for the container until `--timeout`.
  411. A profile's `port` supplies its endpoint when the endpoint is unset or still the product default.
  412. A running container's published port corrects that endpoint, unless the endpoint was chosen on
  413. purpose: typed with `--endpoint`, set in `FLOCI_ENDPOINT`, or on another host. `env` warns on stderr
  414. when it looked the container up and it is not running.
  415. ### `floci status` / `floci gcp status` / `floci az status` / `floci oci status`
  416. ```sh
  417. floci status # auto-detects endpoint from container port mapping
  418. floci status --container myfloci # target a specific container
  419. floci status -o json # structured output
  420. floci status >/dev/null && echo up # exit 0: the instance is up, exit 1: it is not
  421. ```
  422. `status` exits 0 when the server answers and its container, if there is one, is running, and 1
  423. otherwise, in every output format. An instance with no local container (a remote `--endpoint`, a
  424. Compose service under another name) counts as up when it answers.
  425. ### `floci env`
  426. Prints AWS environment variables pointing at the running Floci instance. The default
  427. hostname is `localhost.floci.io` (resolves to `127.0.0.1`, enables virtual-hosted S3 bucket names).
  428. ```sh
  429. eval $(floci env) # bash/zsh: sets all four AWS vars
  430. floci env --shell fish | source # fish
  431. floci env --shell powershell | Invoke-Expression # PowerShell
  432. floci env --host myhost.local # custom hostname
  433. floci env --region eu-west-1 # custom region (default: us-east-1)
  434. floci env -o json # structured output for scripts
  435. ```
  436. Variables exported:
  437. | Variable | Default value |
  438. |----------|---------------|
  439. | `AWS_ENDPOINT_URL` | `http://localhost.floci.io:<port>` |
  440. | `AWS_ACCESS_KEY_ID` | `test` |
  441. | `AWS_SECRET_ACCESS_KEY` | `test` |
  442. | `AWS_DEFAULT_REGION` | `us-east-1` |
  443. ### `floci gcp env`
  444. Prints GCP SDK emulator host variables for the running Floci GCP instance.
  445. ```sh
  446. eval $(floci gcp env) # all emulator host vars
  447. eval $(floci gcp env --service gcs,pubsub) # specific services only
  448. floci gcp env --shell fish | source # fish
  449. floci gcp env -o json # structured output
  450. ```
  451. Variables exported (per enabled service):
  452. | Variable | Service |
  453. |----------|---------|
  454. | `STORAGE_EMULATOR_HOST` | Cloud Storage (gcs) |
  455. | `PUBSUB_EMULATOR_HOST` | Pub/Sub |
  456. | `FIRESTORE_EMULATOR_HOST` | Firestore |
  457. | `DATASTORE_EMULATOR_HOST` | Datastore |
  458. | `SECRET_MANAGER_EMULATOR_HOST` | Secret Manager |
  459. | `IAM_EMULATOR_HOST` | IAM |
  460. SDK support for these variables varies by service and language. Python Secret Manager ignores
  461. `SECRET_MANAGER_EMULATOR_HOST`; set an explicit emulator endpoint and anonymous credentials.
  462. See the [Python Secret Manager recipe](skills/floci/references/gcp.md#python-secret-manager).
  463. ### `floci az env`
  464. Prints Azure connection variables for the running Floci Azure instance.
  465. 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`.
  466. ```sh
  467. eval $(floci az env) # connection string (default)
  468. eval $(floci az env --format sdk-vars) # individual SDK endpoint vars
  469. eval $(floci az env --format sdk-vars --service blob,queue) # specific services only
  470. floci az env --shell fish | source # fish
  471. floci az env -o json # structured output
  472. ```
  473. **Connection string mode** (default) exports:
  474. | Variable | Value |
  475. |----------|-------|
  476. | `AZURE_STORAGE_CONNECTION_STRING` | Full Azurite-compatible connection string |
  477. **SDK vars mode** (`--format sdk-vars`) exports:
  478. | Variable | Default value |
  479. |----------|---------------|
  480. | `AZURE_STORAGE_ACCOUNT` | `devstoreaccount1` |
  481. | `AZURE_STORAGE_KEY` | Azurite dev key |
  482. | `AZURE_STORAGE_BLOB_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1` |
  483. | `AZURE_STORAGE_QUEUE_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1-queue` |
  484. | `AZURE_STORAGE_TABLE_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1-table` |
  485. | `AZURE_FUNCTIONS_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1-functions` |
  486. | `AZURE_APP_CONFIGURATION_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1-appconfig` |
  487. | `AZURE_KEY_VAULT_ENDPOINT` | `http://localhost.floci.io:<port>/devstoreaccount1-keyvault` |
  488. **After `floci az setup`**, both modes also export:
  489. | Variable | Value |
  490. |----------|-------|
  491. | `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 |
  492. | `REQUESTS_CA_BUNDLE` | `~/.floci/az/<container>/ca-bundle.pem`, the public roots plus that instance's certificate |
  493. If the instance's certificate changed since setup (a container recreated without `--persist`),
  494. `floci az env` warns on stderr and tells you to re-run `floci az setup`.
  495. ### `floci az setup`
  496. `az group create`, `az login` and every other control-plane command go to public Azure
  497. unless the `az` CLI is told otherwise. `floci az setup` does it in one step:
  498. 1. fetches the emulator's CA certificate from `/_floci/tls-cert` and writes a CA bundle
  499. (the JDK's public roots plus that certificate);
  500. 2. registers (or updates) an az cloud named after the container (`floci-az` by default) whose ARM and Entra endpoints point at
  501. `https://localhost:<port>`, and makes it the active cloud;
  502. 3. turns off `core.instance_discovery`, which otherwise fails the login with `invalid_instance`;
  503. 4. logs in as a service principal with the dev identity (tenant
  504. `00000000-0000-0000-0000-000000000002`, subscription `00000000-0000-0000-0000-000000000001`).
  505. Everything is kept per instance, in `~/.floci/az/<container>/`, so instances started from
  506. different profiles never share a certificate, cloud or login (see
  507. [Running several instances side by side](#running-several-instances-side-by-side)). By default the
  508. az config itself is isolated there too and `~/.azure` is left untouched; `eval $(floci az env)`
  509. then points `az` at it in the current shell only. `--global` writes to your default az config
  510. instead, and removes that instance's earlier isolated config. Re-running is safe: the cloud is updated, not registered twice.
  511. The az CLI only logs in over HTTPS, so `floci az start` always starts Floci Azure with
  512. `FLOCI_AZ_TLS_ENABLED=true` (HTTP keeps working on the same port). A container started by an
  513. older floci has TLS off; run `floci az restart` once.
  514. ```sh
  515. floci az setup # isolated config under ~/.floci/az/floci-az
  516. eval $(floci az env) # AZURE_CONFIG_DIR + REQUESTS_CA_BUNDLE + connection string
  517. az group create -n my-rg -l westeurope
  518. floci az setup --profile team-b # a second instance: ~/.floci/az/<its container>
  519. eval $(floci az env --profile team-b)
  520. floci az setup --global # use your default az config (~/.azure)
  521. eval $(floci az env) # REQUESTS_CA_BUNDLE, and clears a stale AZURE_CONFIG_DIR
  522. floci az setup --reset # delete the isolated config
  523. floci az setup --reset --global # switch the default az config back to AzureCloud
  524. floci az setup -o json # structured output
  525. ```
  526. Requires the `az` CLI on your `PATH`. `--tenant`, `--subscription`, `--client-id` and
  527. `--client-secret` override the dev identity; Floci Azure never checks the secret.
  528. ### `floci oci env`
  529. Prints OCI endpoint variables for the running Floci OCI instance. OCI SDKs and the
  530. `oci` CLI take a single endpoint for every service, so no per-service variables are needed.
  531. ```sh
  532. eval $(floci oci env) # endpoint vars for CLI, wrappers, and Terraform
  533. floci oci env --shell fish | source # fish
  534. floci oci env -o json # structured output
  535. ```
  536. Variables exported:
  537. | Variable | Purpose |
  538. |----------|---------|
  539. | `OCI_CLI_ENDPOINT` | Default `--endpoint` for the `oci` CLI |
  540. | `FLOCI_OCI_ENDPOINT` | Used by this CLI and the `ocilocal` wrapper |
  541. | `TF_VAR_CLIENT_HOST_OVERRIDES` | Per-client host overrides for the `oracle/oci` Terraform provider |
  542. | `OCI_CLI_PROFILE` | The profile `floci oci setup` wrote (default `FLOCI`); only exported when detected in `~/.oci/config`, and skipped for `DEFAULT` |
  543. ### `floci oci setup`
  544. The OCI CLI and SDKs refuse to run without a config file and an API signing key, even
  545. against an emulator that never validates them. `floci oci setup` creates both in one step:
  546. a locally generated RSA-2048 key at `~/.oci/floci_key.pem` and a `[FLOCI]` profile in
  547. `~/.oci/config` with the emulator's canonical throwaway tenancy. Existing profiles are
  548. never touched; re-running is a no-op.
  549. ```sh
  550. floci oci setup # create key + [FLOCI] profile
  551. floci oci setup --profile-name DEFAULT # write a different profile section
  552. floci oci setup -o json # structured output
  553. # then connect:
  554. eval $(floci oci env) # exports OCI_CLI_PROFILE=FLOCI too
  555. oci os ns get
  556. ```
  557. ### `floci logs` / `floci gcp logs` / `floci az logs` / `floci oci logs`
  558. ```sh
  559. floci logs # last logs from the container
  560. floci logs --tail 50 # last 50 lines
  561. floci logs --since 5m # logs from the last 5 minutes
  562. floci logs --follow # stream live logs (Ctrl-C to stop)
  563. ```
  564. ### `floci wait` / `floci gcp wait` / `floci az wait` / `floci oci wait`
  565. ```sh
  566. floci wait # wait up to 30s (default)
  567. floci wait --timeout 2m # custom timeout (supports s, m, h)
  568. floci wait --service dynamodb # wait until a specific service is ready
  569. floci wait -o json # machine-readable output
  570. ```
  571. ### `floci doctor` / `floci gcp doctor` / `floci az doctor` / `floci oci doctor`
  572. ```sh
  573. floci doctor # run all checks
  574. floci doctor --check docker.installed # run a single check by name
  575. floci doctor -o json # structured output for scripts
  576. floci gcp doctor # GCP-specific checks
  577. floci az doctor # Azure-specific checks (includes az CLI + connection string)
  578. floci oci doctor # OCI-specific checks
  579. ```
  580. ### `floci version` / `floci gcp version` / `floci az version` / `floci oci version`
  581. ```sh
  582. floci version # CLI version, server version, image digest
  583. floci version -o json
  584. ```
  585. `floci version` and `floci status` warn on stderr when the AWS server is older than 1.5.0, the
  586. oldest version this CLI supports. The GCP, Azure and OCI emulators are versioned separately and
  587. have no minimum yet.
  588. ### `floci services` / `floci gcp services` / `floci az services` / `floci oci services`
  589. ```sh
  590. floci services # list all enabled services
  591. floci services -o json
  592. ```
  593. ### `floci reset` / `floci gcp reset` / `floci az reset` / `floci oci reset`
  594. ```sh
  595. floci reset # asks first, then deletes every resource; the emulator keeps running
  596. floci reset --yes # no prompt (required when not on a terminal, e.g. in CI)
  597. floci gcp reset -y -o json
  598. ```
  599. It calls the emulator's `POST <prefix>/state/reset`. The AWS, GCP and OCI emulators serve it; on a
  600. server without it (currently floci-az) the command says reset is not available and exits 1. Without
  601. `--yes` and with no terminal to ask on, it exits 2.
  602. Reset never guesses which server to wipe:
  603. - An `--endpoint` you type is used as given.
  604. - A container you select (`--container`, a profile's `container`, or `FLOCI_CONTAINER`) has to be
  605. running. If it is missing or stopped, nothing is reset.
  606. - An endpoint a profile or `FLOCI_ENDPOINT` supplies is used when no container is selected. A
  607. container that happens to run locally under the default name never takes its place.
  608. - When both a container and an endpoint are configured, they have to be the same server. If they
  609. are not, nothing is reset and you are asked to pass `--endpoint` or `--container`.
  610. - A container on a remote Docker host (`DOCKER_HOST=tcp://other-host:...` or `ssh://...`) is only
  611. reset through an endpoint, since its published port is not on this machine. A daemon on this
  612. machine reached over TCP (`tcp://127.0.0.1:2375`) is local.
  613. When reset refuses to choose a server, the command exits 1 without sending anything.
  614. ### `floci config`
  615. ```sh
  616. floci config show # show active configuration
  617. floci config default-product aws|gcp|az|oci # set the default product (persisted to ~/.floci/config.yaml)
  618. floci config profile list # list saved profiles: container, port, data dir
  619. floci config profile create <name> # create a new profile with the tree's defaults
  620. floci config profile create <name> --container <c> --port <p> --persist <dir> --services <csv> --image <img> --namespace <ns>
  621. floci config profile show <name> # show a profile
  622. floci config profile show <name> --json # the same keys as one row of `config profile list --json`
  623. floci config profile edit <name> # open the profile in $VISUAL or $EDITOR, then check it still reads
  624. floci config profile delete <name> # delete a profile
  625. floci config validate -f docker-compose.yml # validate a Compose file
  626. ```
  627. Each product tree has its own `config show|validate|profile` (`floci gcp config show`, ...), which
  628. uses that product's defaults; `config default-product` is available through bare `floci config`
  629. and `floci aws config`, but not through the GCP, Azure, or OCI config trees.
  630. `config validate` reads the Compose file and checks the service that runs the emulator (found by
  631. its image; a file with a single service is checked whatever its image is):
  632. | Check | Result when it fails |
  633. |---|---|
  634. | 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 |
  635. | 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 |
  636. | The volume at `/app/data` is writable and not bound to a file | error |
  637. | A volume at `/app/data` comes with `<PREFIX>_STORAGE_MODE=persistent`, and the other way round | warning |
  638. | The image tag is not older than the oldest version this CLI supports (AWS tree) | warning |
  639. It exits 1 when there is an error and 0 otherwise. `-o json` and `-o yaml` print
  640. `file`, `service`, `valid`, `errors` and `warnings`, also for a file that cannot be parsed. An
  641. `env_file` is not read, so nothing is said about a storage mode it may set.
  642. #### Profiles
  643. Profiles are stored in `~/.floci/profiles/<name>.yaml`. Pass `--profile <name>` to any command to
  644. load one; `floci config profile create <name>` writes a starter file seeded with the defaults of
  645. the tree you run it under.
  646. ```yaml
  647. name: probe
  648. endpoint: http://localhost:4566
  649. container: floci-probe
  650. image: floci/floci:enforced
  651. port: 4599
  652. persistDir: /tmp/floci-persist
  653. services: s3,lambda
  654. namespace: team-probe
  655. output: json
  656. ```
  657. Each field supplies the default for one flag, so a profile field only affects the commands that
  658. have that flag:
  659. | Profile field | Flag it supplies | Used by |
  660. |---|---|---|
  661. | `endpoint` | `--endpoint` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
  662. | `container` | `--container` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
  663. | `output` | `--output` / `-o` | every command except `update` and the group commands (`floci gcp`, `floci config`, ...) |
  664. | `image` | `--image` | `start`; `restart` re-applies it through the start it runs |
  665. | `port` | `--port` | `start`; `restart` re-applies it through the start it runs |
  666. | `persistDir` | `--persist` | `start`; `restart` re-applies it through the start it runs |
  667. | `services` | `--services` | `start`; `restart` re-applies it through the start it runs |
  668. | `namespace` | `--namespace` | `start`; `restart` re-applies it through the start it runs |
  669. Resolution order, highest first:
  670. ```
  671. command-line flag > --profile <name> > FLOCI_* environment variable > built-in default
  672. ```
  673. So `floci start --profile probe --container other` starts `other`, and a profile beats a
  674. `FLOCI_CONTAINER` exported in your shell. A field the profile leaves out changes nothing.
  675. An unknown or unreadable profile is an error (exit 2), not a silent fall back to the defaults.
  676. That includes `floci config show --profile <name>`, which before 0.2.2 warned and showed the
  677. defaults instead.
  678. A key floci does not read (a typo such as `persist_dir:`) is ignored with a warning that lists
  679. the keys a profile can set.
  680. Values are interpolated by the CLI, so `persistDir: ${env:HOME}/floci-data` expands as you would
  681. expect.
  682. > Profiles are shared by all four product trees: there is one `~/.floci/profiles/` directory, not
  683. > one per product. A profile created under `floci gcp` carries GCP defaults, so passing it to the
  684. > AWS tree will start a GCP container; name them accordingly.
  685. > `floci restart --profile <name>` re-applies the profile's `persistDir`, so state survives the
  686. > restart. A plain `floci restart` has no `--persist` flag of its own and still falls back to the
  687. > defaults.
  688. #### Running several instances side by side
  689. An instance is a profile. Its **container name** is its identity, its **port** is the only thing
  690. that must differ from the other instances, and its **persist dir** keeps its state across
  691. container recreation. Hints for follow-up CLI commands preserve the selected profile, container
  692. and explicit endpoint, and a retried `start` keeps the flags you typed. Every command (`status`, `logs`, `env`, `doctor`, `stop`, ...) finds the
  693. instance through its container, so passing the same `--profile` is all it takes. Any local state
  694. the CLI keeps about an instance lives in `~/.floci/<product>/<container>/`.
  695. Each instance's emulator also gets its own Docker resource namespace, derived from the container
  696. name unless the profile sets `namespace`. That keeps the containers each instance launches (Lambda functions,
  697. ECS tasks, Cloud Run jobs, Service Bus sidecars, ...) apart, so starting one instance never
  698. cleans up another's. `floci config show --profile <name>` prints the namespace it will use.
  699. Leave `endpoint` at the product default: the CLI reads the real host port from the running
  700. container. `config profile create` warns when a new profile reuses another profile's container,
  701. or its port or resource namespace on the same image.
  702. ```sh
  703. # AWS
  704. floci config profile create aws-a --container floci-a --port 4566 --persist ~/.floci/data/aws-a
  705. floci config profile create aws-b --container floci-b --port 14566 --persist ~/.floci/data/aws-b
  706. floci start --profile aws-a && floci start --profile aws-b
  707. eval $(floci env --profile aws-b) # AWS_ENDPOINT_URL points at :14566
  708. # GCP
  709. floci gcp config profile create gcp-b --container floci-gcp-b --port 14588 --persist ~/.floci/data/gcp-b
  710. floci gcp start --profile gcp-b
  711. eval $(floci gcp env --profile gcp-b)
  712. # Azure: setup is per instance too (its own certificate, az cloud and login)
  713. floci az config profile create az-b --container floci-az-b --port 14577 --persist ~/.floci/data/az-b
  714. floci az start --profile az-b
  715. floci az setup --profile az-b
  716. eval $(floci az env --profile az-b) # plain az now talks to floci-az-b only
  717. # OCI: 'floci oci setup' is shared, the endpoint is per instance
  718. floci oci config profile create oci-b --container floci-oci-b --port 14599 --persist ~/.floci/data/oci-b
  719. floci oci start --profile oci-b
  720. eval $(floci oci env --profile oci-b)
  721. floci config profile list # one row per instance
  722. floci stop --profile aws-b # stop one, the others keep running
  723. ```
  724. Without `--persist` an instance starts empty each time its container is recreated. For floci-az
  725. it also gets a new certificate, which `floci az env` reports so you can re-run `floci az setup`.
  726. ### `floci snapshot`
  727. Save and restore named snapshots of Floci AWS state.
  728. ```sh
  729. floci snapshot list
  730. floci snapshot save <name>
  731. floci snapshot load <name>
  732. floci snapshot delete <name>
  733. floci snapshot export <name> -f tarball.tar.gz
  734. floci snapshot import -f tarball.tar.gz
  735. ```
  736. > 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.
  737. ### `floci completion`
  738. ```sh
  739. floci completion bash >> ~/.bashrc
  740. floci completion zsh >> ~/.zshrc
  741. ```
  742. Completion scripts are generated for bash and zsh. Any other shell name is a usage error (exit 2).
  743. The zsh script loads the bash completion through `bashcompinit` and sets up `floci` only: your shell
  744. options and aliases are left as they were.
  745. ### `floci update`
  746. Self-update the CLI in place: downloads the release binary from GitHub, verifies its
  747. sha256 against the release's `sha256sums.txt`, and atomically replaces the running binary.
  748. ```sh
  749. floci update # update to the latest release
  750. floci update --check # exit 0: up to date, 1: update available, 2: the check failed
  751. floci update --version 0.1.7 # install a specific version
  752. floci update --check || floci update # script-friendly: update only when stale
  753. ```
  754. Homebrew installs are managed by brew and are detected and refused; use `brew upgrade floci` there instead.
  755. When run from an interactive terminal, floci also checks for new releases in the
  756. background (at most once per 24h, cached in `~/.floci/update-check.json`) and prints a
  757. hint before the command output when one is available. Set `FLOCI_NO_UPDATE_CHECK=1` to
  758. opt out; the check is automatically disabled in CI and for piped output.
  759. ---
  760. ## Exit Codes
  761. Every command in every tree (`floci`, `floci aws`, `floci gcp`, `floci az`, `floci oci`) follows
  762. the same three codes:
  763. | Code | Meaning |
  764. |---|---|
  765. | `0` | The command did what it was asked. |
  766. | `1` | It ran and failed, or the answer to the question it asks is "no". |
  767. | `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. |
  768. A value the command line accepts but the command then rejects is exit `2` as well, in every
  769. command: an out-of-range `--port`, an unknown `--pull` policy, a `--persist` path that cannot be
  770. used, a `--version` that is not a release version, an unknown product or action, a missing or
  771. invalid name. Exit `1` always means the command ran.
  772. Where a command's codes carry a specific meaning a script can rely on:
  773. | Command | `0` | `1` | `2` |
  774. |---|---|---|---|
  775. | `status` | the instance is up | it is not: the server does not answer, or its container is stopped | bad flag or profile |
  776. | `wait` | ready before `--timeout` | timed out | `--timeout` is not a positive duration |
  777. | `doctor` | every check passed (warnings allowed) | at least one check failed | `--check` names no known check |
  778. | `update --check` | up to date | an update is available | the check itself failed |
  779. | `update` | updated, or already up to date | the update failed; the binary is unchanged | `--version` is not a release version |
  780. | `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 |
  781. | `stop` | stopped, or was not running | no such container, or Docker failed | bad flag or profile |
  782. | `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` |
  783. | `config validate` | no errors (warnings allowed) | errors found, or the file cannot be read | bad flag |
  784. | `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 |
  785. | `config default-product` | saved | the file cannot be written | not `aws`, `gcp`, `az` or `oci` |
  786. | `env` | variables printed | the selected container has no known endpoint | `--shell` is not supported |
  787. | `completion` | script printed | | the shell is not `bash` or `zsh` |
  788. | `snapshot ...` | done | failed, or the server has no snapshot API yet | invalid snapshot name |
  789. `docs/help/` holds the `--help` text of every command, generated from the code. A test fails when
  790. the files and the commands drift apart; regenerate them with
  791. `mvn test -Dtest=HelpSnapshotTest -Dfloci.help.update=true`.
  792. ---
  793. ## CI Usage
  794. ### AWS CI
  795. ```sh
  796. floci start --detach
  797. floci wait --timeout 60s
  798. eval $(floci env)
  799. pytest # or your test command
  800. floci stop --remove
  801. ```
  802. With Docker Compose:
  803. ```yaml
  804. services:
  805. floci:
  806. image: floci/floci:latest
  807. ports:
  808. - "4566:4566"
  809. volumes:
  810. - /var/run/docker.sock:/var/run/docker.sock
  811. ```
  812. > Using Podman or a non-default daemon? Swap the host side of the socket mount for
  813. > your daemon's socket (e.g. `/run/user/1000/podman/podman.sock:/var/run/docker.sock`).
  814. > With the CLI, setting `DOCKER_HOST` is enough; see
  815. > [Docker daemon resolution](#docker-daemon-resolution-podman-rootless-remote-contexts).
  816. ### GCP CI
  817. ```sh
  818. floci gcp start --detach
  819. floci gcp wait --timeout 60s
  820. eval $(floci gcp env)
  821. pytest # or your test command
  822. floci gcp stop --remove
  823. ```
  824. With Docker Compose:
  825. ```yaml
  826. services:
  827. floci-gcp:
  828. image: floci/floci-gcp:latest
  829. ports:
  830. - "4588:4588"
  831. volumes:
  832. - /var/run/docker.sock:/var/run/docker.sock
  833. ```
  834. ### Azure CI
  835. ```sh
  836. floci az start --detach
  837. floci az wait --timeout 60s
  838. eval $(floci az env)
  839. pytest # or your test command
  840. floci az stop --remove
  841. ```
  842. With Docker Compose:
  843. ```yaml
  844. services:
  845. floci-az:
  846. image: floci/floci-az:latest
  847. ports:
  848. - "4577:4577"
  849. volumes:
  850. - /var/run/docker.sock:/var/run/docker.sock
  851. ```
  852. ### OCI CI
  853. ```sh
  854. floci oci start --detach
  855. floci oci wait --timeout 60s
  856. eval $(floci oci env)
  857. pytest # or your test command
  858. floci oci stop --remove
  859. ```
  860. With Docker Compose:
  861. ```yaml
  862. services:
  863. floci-oci:
  864. image: floci/floci-oci:latest
  865. ports:
  866. - "4599:4599"
  867. volumes:
  868. - /var/run/docker.sock:/var/run/docker.sock
  869. ```
  870. ---
  871. ## AI agents
  872. [`skills/floci/`](skills/floci/) is an [Agent Skill](https://agentskills.io) that teaches coding agents (Claude Code,
  873. Codex, Cursor, Kiro, Gemini CLI and others) to work with Floci: install and drive this CLI, wire `aws`, `gcloud`, `az`,
  874. `oci` and the SDKs to the emulators without touching real cloud, write `docker run` commands and Compose files, run
  875. several instances side by side, and look things up in the published documentation of each emulator
  876. ([AWS](https://floci.io/floci/), [Azure](https://floci.io/floci-az/), [GCP](https://floci.io/floci-gcp/),
  877. [OCI](https://floci.io/floci-oci/)) instead of guessing.
  878. ```sh
  879. # Any supported agent (asks which ones to install it for)
  880. npx skills add floci-io/floci-cli
  881. # Claude Code, as a plugin
  882. /plugin marketplace add floci-io/floci-cli
  883. /plugin install floci@floci
  884. ```
  885. In [Kiro](https://kiro.dev), install it as a power: Powers panel, **Add Custom Power**, **Import power from GitHub**,
  886. and enter `https://github.com/floci-io/floci-cli`. The `plugin.json` at the repository root is the
  887. [Agent Plugins](https://agent-plugins.org) manifest Kiro reads. Kiro also loads plain Agent Skills, so copying
  888. `skills/floci/` into `.kiro/skills/` (or `~/.kiro/skills/`) works as well.
  889. Or copy the `skills/floci/` directory into your agent's skills directory (for example `~/.claude/skills/floci/`).
  890. | Part | What it holds |
  891. |---|---|
  892. | `SKILL.md` | Lifecycle, safety rules (fake credentials only, verify the endpoint, explicit product tree) and when to read what |
  893. | `references/` | One page per cloud, plus Docker and Compose, multiple instances and namespaces, CI, troubleshooting, and how to find a page in the docs |
  894. | `assets/compose/` | Compose templates for each emulator and for all four together |
  895. | `scripts/` | `install-floci.sh` and `ensure-running.sh` (bash) |
  896. The skill follows the CLI: `SkillDocsTest` checks every `floci` command it quotes against the real command tree.
  897. ---
  898. ## Scope
  899. `floci-cli` manages Floci's lifecycle, config, state, and diagnostics.
  900. It does **not** wrap the AWS, GCP, Azure, or OCI CLIs, or manage cloud resources directly.
  901. 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.
  902. ---
  903. ## Testcontainers
  904. Running Floci in tests? Use the Testcontainers module for your language instead of scripting the CLI:
  905. | Language | Repository |
  906. |---|---|
  907. | Java | [testcontainers-floci](https://github.com/floci-io/testcontainers-floci) |
  908. | Node.js / TypeScript | [testcontainers-floci-node](https://github.com/floci-io/testcontainers-floci-node) |
  909. | Python | [testcontainers-floci-python](https://github.com/floci-io/testcontainers-floci-python) |
  910. | Go | [testcontainers-floci-go](https://github.com/floci-io/testcontainers-floci-go) |
  911. | .NET | [testcontainers-floci-dotnet](https://github.com/floci-io/testcontainers-floci-dotnet) |
  912. ## Community
  913. - 💬 [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw): quick questions and community chat
  914. - 🗣️ [GitHub Discussions](https://github.com/orgs/floci-io/discussions): ideas, design tradeoffs, and proposals
  915. - 🐛 [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)
  916. - 🛟 [SUPPORT.md](https://github.com/floci-io/.github/blob/main/SUPPORT.md): where to get help, and what community support covers
  917. - [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)
  918. ## Privacy
  919. The Floci CLI and the agent skill in [`skills/floci/`](skills/floci/) collect no data. There is no telemetry, no
  920. analytics, no account and no sign-in, and nothing you do with them is reported to the Floci project.
  921. The only network requests they make are the ones needed to do what you asked:
  922. | Request | To | When |
  923. |---|---|---|
  924. | 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 |
  925. | Binary download | `github.com` (release assets) | Only when you run `floci update` or the install script |
  926. | Image pull | Your container registry (Docker Hub by default) | When `docker` pulls an emulator image on `floci start` |
  927. | 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 |
  928. | Documentation pages | `floci.io` and `raw.githubusercontent.com` | When an agent using the skill looks something up |
  929. Those services see what any HTTP or DNS request shows them (such as your IP address) and apply their own privacy
  930. policies. Everything else stays on your machine: the emulators run locally, your cloud CLIs and SDKs talk to
  931. `localhost`, and profiles and state live under `~/.floci`. The skill tells agents to use only the fake credentials the
  932. emulators accept and never to read or reuse real cloud credentials.
  933. Questions about this: see [Community](#community).
  934. ## License
  935. MIT. See [LICENSE](LICENSE).
  936. ---
  937. <div align="center">
  938. Floci™ is a trademark of Hector Ventura. Code is MIT-licensed; see
  939. [TRADEMARK.md](https://github.com/floci-io/.github/blob/main/TRADEMARK.md) for name and logo use.
  940. </div>
installer/install.ps1 · Bundled script · 56 lines · 1 finding marked
  1. # Floci CLI Windows installer
  2. # Usage: iwr https://floci.io/install.ps1 | iex
    • Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
    • Line 2 on GitHub
  3. [CmdletBinding()]
  4. param(
  5. [string]$Version = "latest",
  6. [string]$InstallDir = "$env:LOCALAPPDATA\floci\bin"
  7. )
  8. $ErrorActionPreference = "Stop"
  9. $Repo = "floci-io/floci-cli"
  10. function Get-LatestVersion {
  11. $response = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest"
  12. return $response.tag_name
  13. }
  14. function Main {
  15. Write-Host "Installing Floci CLI..." -ForegroundColor Cyan
  16. if ($Version -eq "latest") {
  17. $Version = Get-LatestVersion
  18. }
  19. $Arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
  20. $Platform = "windows-$Arch"
  21. $FileName = "floci-$Platform.exe"
  22. $DownloadUrl = "https://github.com/$Repo/releases/download/$Version/$FileName"
  23. Write-Host "Downloading floci $Version for $Platform..."
  24. if (-not (Test-Path $InstallDir)) {
  25. New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
  26. }
  27. $Destination = Join-Path $InstallDir "floci.exe"
  28. Invoke-WebRequest -Uri $DownloadUrl -OutFile $Destination -UseBasicParsing
  29. # Add to PATH if not already there
  30. $CurrentPath = [Environment]::GetEnvironmentVariable("Path", "User")
  31. if ($CurrentPath -notlike "*$InstallDir*") {
  32. [Environment]::SetEnvironmentVariable("Path", "$CurrentPath;$InstallDir", "User")
  33. Write-Host "Added $InstallDir to user PATH (restart your terminal)"
  34. }
  35. Write-Host ""
  36. Write-Host "Floci CLI $Version installed to $Destination" -ForegroundColor Green
  37. Write-Host ""
  38. Write-Host "Quick start:"
  39. Write-Host " floci start"
  40. Write-Host " floci doctor"
  41. Write-Host ' $env:AWS_ENDPOINT_URL="http://localhost:4566"'
  42. Write-Host " aws s3 mb s3://my-bucket"
  43. }
  44. Main
installer/install.sh · Bundled script · 142 lines · 1 finding marked
  1. #!/usr/bin/env sh
  2. # 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
  3. set -e
  4. VERSION="${FLOCI_CLI_VERSION:-latest}"
  5. INSTALL_DIR="${FLOCI_INSTALL_DIR:-/usr/local/bin}"
  6. BINARY="floci"
  7. REPO="floci-io/floci-cli"
  8. SKIP_CHECKSUM="${FLOCI_SKIP_CHECKSUM:-0}"
  9. DOWNLOAD_RETRIES="${FLOCI_DOWNLOAD_RETRIES:-4}"
  10. # Download $1 to $2, retrying on transient failures. GitHub's CDN intermittently
  11. # returns 5xx (e.g. 504) on release assets, and can hand back a 0-byte body, so
  12. # we wrap curl in our own loop with backoff: an empty file is treated as a
  13. # failure and retried. curl's own --retry handles mid-transfer hiccups; the
  14. # outer loop covers cases it doesn't and works uniformly across curl versions.
  15. download() {
  16. _url="$1"
  17. _out="$2"
  18. _attempt=1
  19. while :; do
  20. if curl -fsSL --retry 2 --retry-delay 1 "$_url" -o "$_out" && [ -s "$_out" ]; then
  21. return 0
  22. fi
  23. if [ "$_attempt" -ge "$DOWNLOAD_RETRIES" ]; then
  24. return 1
  25. fi
  26. _delay=$((_attempt * 2))
  27. echo " download failed (attempt ${_attempt}/${DOWNLOAD_RETRIES}), retrying in ${_delay}s..." >&2
  28. sleep "$_delay"
  29. _attempt=$((_attempt + 1))
  30. done
  31. }
  32. detect_platform() {
  33. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  34. ARCH=$(uname -m)
  35. case "$ARCH" in
  36. x86_64) ARCH="amd64" ;;
  37. aarch64|arm64) ARCH="arm64" ;;
  38. *) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
  39. esac
  40. case "$OS" in
  41. linux) PLATFORM="linux-${ARCH}" ;;
  42. darwin) PLATFORM="darwin-${ARCH}" ;;
  43. *) echo "Unsupported OS: $OS" >&2; exit 1 ;;
  44. esac
  45. echo "$PLATFORM"
  46. }
  47. fetch_latest_version() {
  48. _tmp=$(mktemp)
  49. if ! download "https://api.github.com/repos/${REPO}/releases/latest" "$_tmp"; then
  50. rm -f "$_tmp"
  51. echo "Error: could not reach GitHub to determine the latest version." >&2
  52. echo "Check your connection, or pin a version with FLOCI_CLI_VERSION=<tag>." >&2
  53. exit 1
  54. fi
  55. _version=$(grep '"tag_name"' "$_tmp" | sed 's/.*"tag_name": "\(.*\)".*/\1/')
  56. rm -f "$_tmp"
  57. if [ -z "$_version" ]; then
  58. echo "Error: could not parse the latest version from the GitHub API response." >&2
  59. exit 1
  60. fi
  61. echo "$_version"
  62. }
  63. main() {
  64. echo "Installing Floci CLI..."
  65. PLATFORM=$(detect_platform)
  66. if [ "$VERSION" = "latest" ]; then
  67. VERSION=$(fetch_latest_version)
  68. fi
  69. DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${VERSION}/floci-${PLATFORM}"
  70. TMP=$(mktemp)
  71. echo "Downloading floci ${VERSION} for ${PLATFORM}..."
  72. if ! download "$DOWNLOAD_URL" "$TMP"; then
  73. rm -f "$TMP"
  74. echo "Error: failed to download the Floci binary from:" >&2
  75. echo " $DOWNLOAD_URL" >&2
  76. echo "GitHub may be returning a temporary error (e.g. HTTP 504). Please retry shortly." >&2
  77. exit 1
  78. fi
  79. chmod +x "$TMP"
  80. # Verify checksum if sha256sum is available
  81. if [ "$SKIP_CHECKSUM" != "1" ] && command -v sha256sum >/dev/null 2>&1; then
  82. SUMS_URL="https://github.com/${REPO}/releases/download/${VERSION}/sha256sums.txt"
  83. SUMS_TMP=$(mktemp)
  84. # Fetch to a file so a failed download is caught here, not silently
  85. # swallowed inside a pipeline (which would yield an empty expected sum
  86. # and a misleading "checksum mismatch").
  87. if ! download "$SUMS_URL" "$SUMS_TMP"; then
  88. rm -f "$TMP" "$SUMS_TMP"
  89. echo "Error: failed to download checksums from:" >&2
  90. echo " $SUMS_URL" >&2
  91. echo "Cannot verify the binary's integrity. Please retry, or set" >&2
  92. echo "FLOCI_SKIP_CHECKSUM=1 to install without verification." >&2
  93. exit 1
  94. fi
  95. EXPECTED=$(grep "floci-${PLATFORM}\$" "$SUMS_TMP" | awk '{print $1}')
  96. rm -f "$SUMS_TMP"
  97. if [ -z "$EXPECTED" ]; then
  98. rm -f "$TMP"
  99. echo "Error: no checksum entry for floci-${PLATFORM} in sha256sums.txt." >&2
  100. echo "Please report this at https://github.com/${REPO}/issues." >&2
  101. exit 1
  102. fi
  103. ACTUAL=$(sha256sum "$TMP" | awk '{print $1}')
  104. if [ "$EXPECTED" != "$ACTUAL" ]; then
  105. rm -f "$TMP"
  106. echo "Checksum mismatch for floci-${PLATFORM} — the download may be corrupted." >&2
  107. echo " expected: $EXPECTED" >&2
  108. echo " actual: $ACTUAL" >&2
  109. echo "Please retry the install." >&2
  110. exit 1
  111. fi
  112. echo "Checksum verified."
  113. fi
  114. # Install
  115. if [ -w "$INSTALL_DIR" ]; then
  116. mv "$TMP" "${INSTALL_DIR}/${BINARY}"
  117. else
  118. echo "Installing to ${INSTALL_DIR} requires sudo..."
  119. sudo mv "$TMP" "${INSTALL_DIR}/${BINARY}"
  120. fi
  121. echo ""
  122. echo "Floci CLI ${VERSION} installed to ${INSTALL_DIR}/${BINARY}"
  123. echo ""
  124. echo "Quick start:"
  125. echo " floci start # launch Floci"
  126. echo " floci doctor # check your environment"
  127. echo " export AWS_ENDPOINT_URL=http://localhost:4566"
  128. echo " aws s3 mb s3://my-bucket # use the AWS CLI against Floci"
  129. }
  130. main "$@"
skills/floci/scripts/install-floci.sh · Bundled script · 86 lines · 2 findings marked
  1. #!/usr/bin/env bash
  2. # Install floci-cli if it is missing. Linux and macOS.
  3. # 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
  4. #
  5. # Usage: install-floci.sh [--method brew|script] [--version <tag>] (tags have no 'v': 0.4.0)
  6. #
  7. # Defaults: Homebrew when brew is on PATH, otherwise the official install script into
  8. # ~/.local/bin, which needs no sudo (the script's own default, /usr/local/bin, prompts for
  9. # sudo, which hangs a non-interactive agent). Override the dir with FLOCI_INSTALL_DIR.
  10. set -euo pipefail
  11. method=""
  12. version="${FLOCI_CLI_VERSION:-latest}"
  13. while [[ $# -gt 0 ]]; do
  14. case "$1" in
  15. --method) method="${2:-}"; shift 2 ;;
  16. --version) version="${2:-}"; shift 2 ;;
  17. -h|--help) sed -n '2,10p' "$0"; exit 0 ;;
  18. *) echo "unknown argument: $1" >&2; exit 64 ;;
  19. esac
  20. done
  21. if command -v floci >/dev/null 2>&1; then
  22. echo "floci already installed: $(command -v floci)"
  23. floci version 2>/dev/null | head -1 || true
  24. if [[ "$version" != "latest" ]]; then
  25. echo "NOTE: --version $version was not applied. Use 'floci update --version $version' (or brew) to change the installed version." >&2
  26. fi
  27. exit 0
  28. fi
  29. case "$(uname -s)" in
  30. Linux|Darwin) ;;
  31. *) echo "Unsupported OS for this script. On Windows run: iwr https://floci.io/install.ps1 | iex" >&2; exit 1 ;;
  32. esac
  33. if [[ -z "$method" ]]; then
  34. if command -v brew >/dev/null 2>&1 && [[ "$version" == "latest" ]]; then
  35. method="brew"
  36. else
  37. method="script"
  38. fi
  39. fi
  40. case "$method" in
  41. brew)
  42. command -v brew >/dev/null 2>&1 || { echo "brew not found; use --method script" >&2; exit 1; }
  43. if [[ "$version" != "latest" ]]; then
  44. echo "NOTE: Homebrew installs the current release; --version $version is ignored. Use --method script to pin." >&2
  45. fi
  46. brew install floci-io/floci/floci
  47. ;;
  48. script)
  49. command -v curl >/dev/null 2>&1 || { echo "curl is required" >&2; exit 1; }
  50. dir="${FLOCI_INSTALL_DIR:-$HOME/.local/bin}"
  51. mkdir -p "$dir"
  52. tmp="$(mktemp)"
  53. trap 'rm -f "$tmp"' EXIT
  54. curl -fsSL https://floci.io/install.sh -o "$tmp"
  55. FLOCI_INSTALL_DIR="$dir" FLOCI_CLI_VERSION="$version" sh "$tmp"
  56. case ":$PATH:" in
  57. *":$dir:"*) ;;
  58. *)
  59. echo
  60. echo "NOTE: $dir is not on PATH. For this shell: export PATH=\"$dir:\$PATH\""
  61. echo "To make it permanent, add that line to ~/.bashrc or ~/.zshrc (ask the user first)."
  62. export PATH="$dir:$PATH"
  63. ;;
  64. esac
  65. ;;
  66. *)
  67. echo "unknown method: $method (use brew or script)" >&2; exit 64 ;;
  68. esac
  69. if ! command -v floci >/dev/null 2>&1; then
  70. echo "install finished but floci is not on PATH" >&2
  71. exit 1
  72. fi
  73. floci version 2>/dev/null | head -1 || true
  74. # The emulators run as containers; warn early if there is no Docker-compatible runtime.
  75. if ! command -v docker >/dev/null 2>&1; then
  76. echo "WARNING: docker CLI not found. Floci needs Docker (or Podman via DOCKER_HOST) to run the emulators." >&2
  77. elif ! docker info >/dev/null 2>&1; then
  78. echo "WARNING: docker is installed but the daemon is not reachable. Start Docker, or set DOCKER_HOST for Podman." >&2
  79. fi

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.