> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/quickstarts/cli.md).

# CLI quickstart

Install the flora command-line tool and run your first FLORA Technique from the terminal, with output filtering and a polling loop for scripts and CI.

The `flora` CLI wraps the [FLORA API](https://docs.flora.ai/api.md) for shell scripts, CI jobs and quick checks from the terminal. Install it with Go, set your API key, and you can list, run and poll Techniques without writing code.

{% hint style="info" %}
The CLI is generated from an earlier version of the API and covers Techniques, Technique runs, runs, generations, assets, workspaces, projects and models. For newer endpoints, such as bulk uploads or LoRA training, use the [TypeScript SDK](https://docs.flora.ai/api/quickstarts/typescript.md) or curl.
{% endhint %}

## Install

You need [Go](https://go.dev/doc/install) 1.22 or later.

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

This puts a `flora` binary in your Go bin directory (`$(go env GOPATH)/bin`). If your shell can't find it, add that directory to your `PATH`:

```bash
export PATH="$PATH:$(go env GOPATH)/bin"
flora --version
```

## Configure

Set your API key in the environment. Create one in **Settings → API Keys** (see [Authentication](https://docs.flora.ai/api/platform/authentication.md)).

```bash
export FLORA_API_KEY="ak_XXXX"
```

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

```bash
flora workspaces list --api-key "ak_XXXX"
```

## First run, end to end

Replace `portrait-enhancer` with your Technique's slug (the last part of its URL in FLORA) or its `tech_` ID.

```bash
# 1. List Techniques
flora techniques list

# 2. Read a Technique's inputs and price per run
flora techniques retrieve --technique-id portrait-enhancer

# 3. Start a run; match each input's id and type from step 2
flora techniques:runs create \
  --technique-id portrait-enhancer \
  --input '{id: input_image, type: imageUrl, value: "https://example.com/photo.jpg"}' \
  --mode async

# 4. Read the run by ID
flora techniques:runs retrieve \
  --technique-id portrait-enhancer \
  --run-id run_abc123
```

`--input` takes JSON or YAML. Repeat it once per input.

## Output formats

Choose a format with `--format` (`auto`, `json`, `jsonl`, `pretty`, `raw`, `yaml` or `explore`). Pull out fields with `--transform`, which uses [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md), and add `-r` to print a string without quotes:

```bash
# Just the URLs from a completed run
flora techniques:runs retrieve \
  --technique-id portrait-enhancer \
  --run-id run_abc123 \
  --transform 'outputs.#.url'
```

## Polling with a shell loop

Each poll counts against your workspace's rate limit, so wait about 15 seconds between polls.

```bash
SLUG=portrait-enhancer

RUN_ID=$(flora techniques:runs create \
  --technique-id "$SLUG" \
  --input '{id: input_image, type: imageUrl, value: "https://example.com/photo.jpg"}' \
  --mode async \
  --transform run_id -r)

while true; do
  STATUS=$(flora techniques:runs retrieve \
    --technique-id "$SLUG" \
    --run-id "$RUN_ID" \
    --transform status -r)

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

flora techniques:runs retrieve \
  --technique-id "$SLUG" \
  --run-id "$RUN_ID" \
  --transform 'outputs.#.url'
```

## Idempotency

Pass `--idempotency-key` when you create a run you might retry. Reusing the key in the same workspace returns the run it first created:

```bash
flora techniques:runs create \
  --technique-id portrait-enhancer \
  --input '{id: input_image, type: imageUrl, value: "https://example.com/photo.jpg"}' \
  --mode async \
  --idempotency-key "spring-launch-DE"
```

See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).

## Errors and request IDs

A non-2xx response exits with a non-zero status and prints the API error to stderr. Add `--debug` to print the full HTTP exchange, including the `Flora-Request-Id` response header that support asks for:

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

See [Errors](https://docs.flora.ai/api/platform/errors.md) for every code.

## What's next

* Run `flora --help`, or `flora <resource> <command> --help`, for every command and flag.
* [Authentication](https://docs.flora.ai/api/platform/authentication.md): key scopes, rotation and security.
* [Recipes](https://docs.flora.ai/api/recipes.md): end-to-end patterns, several with a CLI version.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/quickstarts/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
