---
title: CLI | FLORA API
description: Install the FLORA CLI and run your first Technique from the terminal.
---

The `flora` CLI wraps the [FLORA REST API](/api/index.md). Useful for shell scripts, CI jobs, quick experiments, and inspecting your workspace from the terminal.

## Install

Terminal window

```
go install github.com/florafauna-ai/flora-cli/cmd/flora@latest
```

This drops a `flora` binary into `$GOPATH/bin` (or `$GOBIN`). Ensure that directory is on your `PATH`.

Terminal window

```
flora --version
```

## Configure

Set your API key in the environment:

Terminal window

```
export FLORA_API_KEY="sk_live_XXXX"
```

Or pass `--api-key` on each command:

Terminal window

```
flora workspaces list --api-key "sk_live_XXXX"
```

## First run, end to end

Terminal window

```
# 1. List Techniques
flora techniques list


# 2. Retrieve a Technique to see its inputs
flora techniques retrieve --technique-id thumbnail-v3


# 3. Start a run
flora techniques:runs create \
  --technique-id thumbnail-v3 \
  --input '{id: prompt, type: text, value: "Smart living, simple — warm minimalism"}' \
  --mode async


# 4. Poll the run by ID
flora techniques:runs retrieve \
  --technique-id thumbnail-v3 \
  --run-id run_abc123
```

## Output formats

By default the CLI prints JSON. Most commands support `--output` for alternative formats and `--jq` for inline filtering:

Terminal window

```
# Just the URLs from a completed run
flora techniques:runs retrieve \
  --technique-id thumbnail-v3 \
  --run-id run_abc123 \
  --jq '.outputs[].url'
```

## Polling with a shell loop

Terminal window

```
RUN_ID=$(flora techniques:runs create \
  --technique-id thumbnail-v3 \
  --input '{id: prompt, type: text, value: "..."}' \
  --mode async \
  --jq '.runId' -r)


while true; do
  STATUS=$(flora techniques:runs retrieve \
    --technique-id thumbnail-v3 \
    --run-id "$RUN_ID" \
    --jq '.status' -r)


  case "$STATUS" in
    completed) echo "done"; break ;;
    failed)    echo "failed"; exit 1 ;;
    *)         sleep 2 ;;
  esac
done


flora techniques:runs retrieve \
  --technique-id thumbnail-v3 \
  --run-id "$RUN_ID" \
  --jq '.outputs[].url' -r
```

## Idempotency

Pass `--idempotency-key` on any mutation you might retry:

Terminal window

```
flora techniques:runs create \
  --technique-id thumbnail-v3 \
  --input '...' \
  --mode async \
  --idempotency-key "q3-thumb-DE"
```

See [Idempotency](/platform/idempotency/index.md) for the full semantics.

## Errors and request IDs

Non-2xx responses print to stderr with the request ID and error code. Capture both:

Terminal window

```
if ! flora techniques:runs retrieve --technique-id ... --run-id ... 2> err.log; then
  cat err.log
  exit 1
fi
```

See [Errors](/platform/errors/index.md).

## What’s next

- **[Authentication](/platform/authentication/index.md)** — keys, rotation, security.
- **[Recipes](/recipes/generate-a-grid/index.md)** — common end-to-end patterns.
- **[API Reference](/api/cli/index.md)** — every command, subcommand, and flag.