### Setup and Verification Commands (Bash)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

These bash commands guide through setting up the fz-cli environment, including installation and verifying the installation by checking the help and version information.

```bash
# Setup
cd fz-cli
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Verify installation
fz --help
fz --version
```

--------------------------------

### Install FluidZero CLI

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Install the FluidZero CLI using Homebrew, pip, or by building from source. Pip installation is recommended for general use, while building from source is useful for development.

```bash
# Homebrew (macOS)
brew install fluidzero/tap/fz

# pip
pip install fluidzero-cli

# From source
git clone https://github.com/fluidzero/fz-cli.git
cd fz-cli
pip install -e .
```

--------------------------------

### Configuration File Example (TOML)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

An example TOML configuration file demonstrating default settings for API URL, project ID, output format, upload concurrency, retry attempts, run polling interval, and timeout.

```toml
# ~/.config/fluidzero/config.toml
[defaults]
api_url = "https://api-staging.fluidzero.ai"
project = "e94af89d-..."
output = "table"

[upload]
concurrency = 4
retry_attempts = 3

[runs]
poll_interval = 2
timeout = 600
```

--------------------------------

### fz-cli Credentials File Example (JSON)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

An example of the credentials.json file used by fz-cli to store authentication tokens and related information. This file is typically located at ~/.config/fluidzero/credentials.json and should have restricted permissions (0600).

```json
{
  "access_token": "eyJ...",
  "refresh_token": "AthaZXNE...",
  "expires_at": 1771486528,
  "api_url": "http://localhost:8000",
  "client_id": "client_01KGA8ECKMDH8GWPZR00QGPTBZ"
}
```

--------------------------------

### Example Workflow Commands (Bash)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

Bash commands illustrating common workflows, such as listing projects, uploading documents, creating runs, executing composite runs, and searching documents.

```bash
# Example workflows
fz projects list
fz documents upload -p <project-id> *.pdf --wait
fz runs create -p <project-id> --schema <schema-id> --wait
fz run -p <project-id> --schema <schema-id> --upload *.pdf --wait  # composite
fz search "quarterly revenue" -p <project-id>
```

--------------------------------

### Create and Manage Prompts with fz-cli

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Allows creation and management of extraction prompts, either from a text file or inline text. Supports listing, getting details, and versioning prompts.

```bash
# Create prompt from file
fz prompts create "Invoice Extraction Prompt" -p e94af89d-...
  --file ./prompts/invoice-prompt.txt \
  --description "Custom instructions for invoice extraction" \
  --message "Initial version"

# Create with inline text
fz prompts create "Simple Prompt" -p e94af89d-...
  --text "Extract all monetary values and dates from the document. Format dates as YYYY-MM-DD."

# List prompts
fz prompts list -p e94af89d-...

# Get prompt details
fz prompts get prompt_abc123

# Create new version
fz prompts versions create prompt_abc123 \
  --file ./prompts/invoice-prompt-v2.txt \
  --message "Improved line item extraction"

# Get specific version text
fz prompts versions get prompt_abc123 --version 2 --text-only
```

--------------------------------

### List and Get Schemas with fz-cli

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Lists all available schemas within a project or retrieves detailed information for a specific schema by its ID.

```bash
# List all schemas
fz schemas list -p e94af89d-...

# Output:
# ID           NAME            VERSIONS  RUNS  LATEST  CREATED
# sch_abc123   Invoice Schema  3         42    3       2024-01-15
# sch_def456   Contract Terms  2         18    2       2024-02-20

# Get schema details
fz schemas get sch_abc123
```

--------------------------------

### Manage FluidZero Projects (Get, Update, Delete)

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Perform operations on individual projects, including retrieving their details, updating their metadata (name and description), and deleting them. Deletion can be confirmed interactively or bypassed with a `--confirm` flag.

```bash
# Get project details (uses default project if set)
fz projects get e94af89d-1234-5678-9abc-def012345678

# Update project metadata
fz projects update e94af89d-1234-5678-9abc-def012345678 \
  --name "Invoice Analysis v2" \
  --description "Updated invoice extraction pipeline"

# Delete project (with confirmation)
fz projects delete e94af89d-1234-5678-9abc-def012345678

# Delete without confirmation prompt
fz projects delete e94af89d-1234-5678-9abc-def012345678 --confirm
```

--------------------------------

### Get and Delete Documents with fz-cli

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Retrieves details for a specific document or deletes a document, with an option to bypass confirmation.

```bash
# Get document details
fz documents get doc_123abc456def

# Delete document (with confirmation)
fz documents delete doc_123abc456def

# Delete without prompt
fz documents delete doc_123abc456def --confirm
```

--------------------------------

### Create FluidZero Project

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Create a new project within your FluidZero organization. You can provide an optional description to further detail the project's purpose. The command returns the details of the newly created project, including its ID.

```bash
fz projects create "Q1 Financial Reports" --description "Quarterly financial document extraction"

# Output:
# Project created: f7e8d9c0-1234-5678-90ab-cdef12345678
# {
#   "id": "f7e8d9c0-1234-5678-90ab-cdef12345678",
#   "name": "Q1 Financial Reports",
#   "description": "Quarterly financial document extraction",
#   "documentCount": 0,
#   "schemaCount": 0,
#   "runCount": 0,
#   "createdAt": "2024-03-15T10:30:00Z"
# }
```

--------------------------------

### Runs - Get Results

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Retrieve extraction results from a completed run, with options to fetch specific results or paginate.

```APIDOC
## Runs - Get Results

### Description
Retrieve extraction results from a completed run.

### Method
`fz runs results [run_id]`

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The ID of the run to retrieve results from

#### Query Parameters
- **--result** (string) - Optional - The ID of a specific result to fetch
- **--limit** (integer) - Optional - Number of results to return
- **--offset** (integer) - Optional - Number of results to skip
- **-o json** (boolean) - Optional - Output results in JSON format

### Request Example
```bash
# Get all results
fz runs results run_123abc

# Get specific result by ID
fz runs results run_123abc --result result_xyz789

# Pagination for large result sets
fz runs results run_123abc --limit 50 --offset 100

# JSON output for processing
fz -o json runs results run_123abc
```

### Response
#### Success Response (200)
- **SEQ** (integer) - Sequence number of the result
- **DOCUMENT** (string) - ID of the document the result is from
- **QUALITY** (float) - Quality score of the extraction
- **DATA** (object) - The extracted data

#### Response Example (Table)
```
SEQ  DOCUMENT    QUALITY  DATA
1    doc_abc123  0.95     {"invoice_number": "INV-001", "total": 1250.00, ...}
2    doc_def456  0.92     {"invoice_number": "INV-002", "total": 890.50, ...}
```

#### Response Example (JSON)
```json
{
  "items": [
    {
      "sequenceNumber": 1,
      "documentId": "doc_abc123",
      "quality": 0.95,
      "data": {"invoice_number": "INV-001", "total": 1250.00}
    },
    {
      "sequenceNumber": 2,
      "documentId": "doc_def456",
      "quality": 0.92,
      "data": {"invoice_number": "INV-002", "total": 890.50}
    }
  ],
  "total": 2
}
```
```

--------------------------------

### Using M2M Credentials for CI/CD (Bash)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

Bash commands demonstrating how to set environment variables for M2M authentication and then use fz-cli to interact with projects.

```bash
# Using M2M credentials (CI/CD)
export FZ_CLIENT_ID=client_01K...
export FZ_CLIENT_SECRET=124e12a...
export FZ_API_URL=http://localhost:8000
fz projects list  # Uses M2M auth automatically
```

--------------------------------

### Composite Run Command with fz-cli

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Combines file uploading and run creation into a single command. Supports specifying the project, schema, multiple files for upload, and waiting for the run to complete.

```bash
# Upload files and run extraction
fz run -p e94af89d-...
  --schema sch_abc123 \
  --upload ./invoices/invoice_001.pdf \
  --upload ./invoices/invoice_002.pdf \
  --wait

# Output:
# Uploading 2 file(s)...
# Run created: run_789xyz
#   Status: running  Progress: 50%  Processing documents
#   Status: completed  Progress: 100%  Done
# Run completed with 2 result(s).
# {
#   "items": [
#     {"sequenceNumber": 1, "documentId": "doc_abc", "data": {...}},
#     {"sequenceNumber": 2, "documentId": "doc_def", "data": {...}}
#   ],
#   "total": 2
# }
```

--------------------------------

### Configure CLI - FluidZero CLI

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Configure CLI behavior using global configuration files (e.g., `~/.config/fluidzero/config.toml`), project-local configuration files (e.g., `.fluidzero.toml`), and environment variables. Supports setting defaults for API URL, project ID, output format, and upload/run settings.

```bash
# Global config: ~/.config/fluidzero/config.toml
cat > ~/.config/fluidzero/config.toml << 'EOF'
[defaults]
api_url = "https://api.fluidzero.ai"
project = "e94af89d-1234-5678-9abc-def012345678"
output = "table"

[upload]
concurrency = 4
retry_attempts = 3

[runs]
poll_interval = 2
timeout = 600
EOF

# Project-local config: .fluidzero.toml (in project directory)
cat > .fluidzero.toml << 'EOF'
project = "e94af89d-1234-5678-9abc-def012345678"

[defaults]
output = "json"

[upload]
concurrency = 8
EOF

# Environment variables
export FZ_API_URL="https://api.fluidzero.ai"
export FZ_PROJECT_ID="e94af89d-1234-5678-9abc-def012345678"
export FZ_OUTPUT="json"
export FZ_CLIENT_ID="client_01KABC..."      # M2M auth
export FZ_CLIENT_SECRET="secret..."          # M2M auth
export NO_COLOR=1                            # Disable colors
```

--------------------------------

### Global Flags Usage (Bash)

Source: https://github.com/fluidzero/fz-cli/blob/main/CLAUDE.md

Bash examples showing how to use global flags like output format (-o json, -o csv), quiet mode (-q), and verbose mode (-v) before the subcommand.

```bash
# Global flags come BEFORE subcommand (Click convention)
fz -o json projects list       # JSON output
fz -o csv projects list        # CSV output
fz -q projects list            # Quiet (no output)
fz -v projects list            # Verbose (shows HTTP requests on stderr)
```

--------------------------------

### Get Run Results with fz-cli

Source: https://context7.com/fluidzero/fz-cli/llms.txt

Retrieves extraction results from a completed run. Supports fetching all results, specific results by ID, and paginating large result sets. Can output JSON for programmatic processing.

```bash
# Get all results
fz runs results run_123abc

# Get specific result by ID
fz runs results run_123abc --result result_xyz789

# Pagination for large result sets
fz runs results run_123abc --limit 50 --offset 100

# JSON output for processing
fz -o json runs results run_123abc | jq '.items[] | .data'

# Output (table):
# SEQ  DOCUMENT    QUALITY  DATA
# 1    doc_abc123  0.95     {"invoice_number": "INV-001", "total": 1250.00, ...}
# 2    doc_def456  0.92     {"invoice_number": "INV-002", "total": 890.50, ...}
```