> ## 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. The 1.0 line is a release candidate, so `pip` needs `--pre`.

```bash theme={null}
pip install --pre 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. Fields are matched to the previous version by name, or by `persistent_id` when the schema file carries one.

| 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. You can 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 are stable across those edits when you keep `persistent_id` in the schema file.

## Exit status

`afx` exits `1` with an `Error:` line on stderr when the key is missing, the input is invalid, the API rejects a request (with the status and `error_code`), the run ends in `error` or `cancelled`, or the wait times out.