Skip to content
FLORA FLORA API

CLI

The flora CLI wraps the FLORA REST API. Useful for shell scripts, CI jobs, quick experiments, and inspecting your workspace from the terminal.

Install

Section titled “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

Section titled “Configure”

Set your API key in the environment:

Terminal window
export FLORA_API_KEY="ak_XXXX"

Or pass --api-key on each command:

Terminal window
flora workspaces list --api-key "ak_XXXX"

First run, end to end

Section titled “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

Section titled “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

Section titled “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 '.run_id' -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

Section titled “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 for the full semantics.

Errors and request IDs

Section titled “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.

What’s next

Section titled “What’s next”