> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command line (afx)

> Parse a file, extract fields, run and manage workflows from the terminal with afx, the command the Python package installs.

`afx` is the command line that ships with the [Python SDK](/api-reference-v3/sdks/python). It covers the one-off jobs you do not want to write code for: parse a file to markdown, extract a few fields, run an existing workflow, and list or delete workflows.

## Install

`afx` is the `anyformat` package's console script.

```bash theme={null}
pip install anyformat
afx --version
```

Run `afx` with no arguments for the banner, or `afx --help` for the command list.

## Auth

Every command reads the API key from `ANYFORMAT_API_KEY`, or from `--api-key`. A missing key exits with `Error: API key is required. Set --api-key or ANYFORMAT_API_KEY.`

```bash theme={null}
export ANYFORMAT_API_KEY=af_...
```

Every command also takes `--base-url` (default `https://api.anyformat.ai`) for a non-production deployment.

## Commands

Commands in the order `afx --help` lists them. Progress lines go to stderr; results go to stdout, so you can pipe them.

### extract

Creates a workflow with one [Parse](/guides/nodes/parse) node and one [Extract](/guides/nodes/extract) node, uploads the file, runs it, and prints the fields. Give the fields inline with `--field`, or as a JSON file with `--schema`. At least one is required.

| Option | Default | What it does |
| - | - | - |
| `FILE` (argument) | required | Path to the file to process. |
| `--field name:description` | | A string field. Repeatable. |
| `--schema PATH` | | JSON file with the full schema. Supports every scalar type and one level of `object` nesting. |
| `--name` | `anyformat-cli/extract <timestamp>` | Workflow name. |
| `--parse-mode` | `standard` | Parse tier: `standard`, `agentic`, `lite` or `flash`. |
| `--on-conflict` | server default (`error`) | `error` rejects a filename that already exists in the workflow with `409`; `rename` auto-renames it. |
| `--timeout` | `300` | Seconds to wait for the run. |
| `--json` / `--table` | `--table` | Output format. |
| `--output PATH`, `-o` | stdout | Write the results to a file. |

```bash theme={null}
afx extract invoice.pdf \
  --field "invoice_number:The unique invoice identifier" \
  --field "total_amount:Total invoice amount" \
  --parse-mode agentic --json
```

The `--schema` file is a JSON array. Each entry has `name`, `type` and `description`; an `object` entry adds `fields`. Supported types: `string`, `integer`, `float`, `boolean`, `date`, `datetime`, `object`. `enum` and `multi_select` are not supported on the command line.

```json theme={null}
[
  { "name": "vendor", "type": "string", "description": "Vendor name on the invoice." },
  { "name": "total",  "type": "float",  "description": "Grand total." },
  { "name": "line_items", "type": "object", "description": "One row per line item.", "fields": [
    { "name": "sku",    "type": "string", "description": "Stock keeping unit." },
    { "name": "amount", "type": "float",  "description": "Line amount." }
  ]}
]
```

The table view prints scalar fields with their confidence and summarises object fields as row counts; use `--json` to see the rows.

### run

Runs an existing workflow, built in Studio or with an SDK, against a file and prints the fields.

| Option | Default | What it does |
| - | - | - |
| `FILE` (argument) | required | Path to the file to process. |
| `--workflow-id`, `-w` | required | The workflow to run. |
| `--on-conflict` | server default (`error`) | `error` or `rename`, as for `extract`. |
| `--timeout` | `300` | Seconds to wait for the run. |
| `--json` / `--table` | `--json` | Output format. |
| `--output PATH`, `-o` | stdout | Write the results to a file. |

```bash theme={null}
afx run invoice.pdf -w 0686bb97-8c30-70f0-8000-97669e000eb8 > result.json
```

### parse

Parses a file with the atomic parse operation (a fast, lite parse) and prints the markdown. No workflow is created.

| Option | Default | What it does |
| - | - | - |
| `FILE` (argument) | required | Path to the file to parse. |
| `--timeout` | `300` | Seconds to wait. |
| `--poll-interval` | `3.0` | Seconds between status polls. |
| `--json` / `--table` | `--table` | `--table` prints the markdown (rendered on a terminal); `--json` prints `{ "markdown": ... }`. |
| `--output PATH`, `-o` | stdout | Write the result to a file. |

```bash theme={null}
afx parse contract.pdf -o contract.md
```

### update-workflow

Replaces an existing workflow's graph with a new Parse + Extract pair built from `--field` and `--schema`, the same way `extract` builds one. A field keeps its identity only when the schema file carries its `persistent_id`. Nothing matches by name. A field without one is new, and loses the quality metrics, ground truth and analytics attached to the old field. Fetch the current ids with `afx get <workflow-id>` before updating.

| Option | Default | What it does |
| - | - | - |
| `--workflow-id` | required | The workflow to update. |
| `--field name:description` | | A string field. Repeatable. |
| `--schema PATH` | | JSON schema file, as for `extract`. May carry `persistent_id` per field. |
| `--name` | `anyformat-cli/update-workflow <timestamp>` | New workflow name. |
| `--parse-mode` | `standard` | Parse tier. |

```bash theme={null}
afx update-workflow --workflow-id 0686bb97-8c30-70f0-8000-97669e000eb8 --schema fields.json
```

### list

Lists your organization's workflows, newest first, as a table of id, name and creation time.

| Option | Default | What it does |
| - | - | - |
| `--limit` | `20` | Rows to show, 1 to 100. A note on stderr says when more exist. |

```bash theme={null}
afx list --limit 50
```

### get

Prints a workflow's typed definition as JSON: the same `{ name, description, nodes, edges }` shape the [create endpoint](/api-reference-v3/workflows/create) accepts.

```bash theme={null}
afx get 0686bb97-8c30-70f0-8000-97669e000eb8 > workflow.json
```

### delete

Deletes a workflow, with its document packets and runs. Asks for confirmation unless `--yes` is given.

| Option | Default | What it does |
| - | - | - |
| `--yes`, `-y` | off | Skip the confirmation prompt. |

```bash theme={null}
afx delete 0686bb97-8c30-70f0-8000-97669e000eb8 -y
```

### runs

Lists a workflow's runs, newest first: run id, document packet id, status and creation time.

| Option | Default | What it does |
| - | - | - |
| `--limit` | `20` | Rows to show, 1 to 100. |

```bash theme={null}
afx runs 0686bb97-8c30-70f0-8000-97669e000eb8
```

## What a CLI workflow is

`afx extract` and `afx update-workflow` build the same typed graph the SDKs and Studio use: a `parse` node with the chosen `mode`, one `extract` node with your fields, and one edge between them. `afx get` shows it. Open a CLI-created workflow in Studio, run it with `afx run` or either SDK, and edit it with `afx update-workflow` or `PATCH /v3/workflows/{id}/`. The field ids stay stable across those edits as long as the schema file keeps `persistent_id`.

## Exit status

`afx` exits `1` and prints an `Error:` line on stderr in five cases: the key is missing, the input is invalid, the API rejects the request, the run ends in `error` or `cancelled`, or the wait times out. A rejected request also prints the status and the `error_code`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.