> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/cli/usage/command-structure/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Command structure

> How Deel CLI commands are organized, and how to discover their contracts from the terminal

Every CLI invocation follows the same shape:

```text
deel <group> <action> [--<variant>] [action options] [global options]
```

| Part           | Example                                   | Description                                                                     |
| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------- |
| `group`        | `adjustments`                             | The API resource, taken from the first path segment of the operation            |
| `action`       | `create`, `create-bulk`, `list`, `status` | The operation on that resource                                                  |
| `variant`      | `--invoice`, `--payroll`                  | Selects one of several operations that share the same group and action          |
| action options | `--job_id <id>`, `--limit 20`             | Path and query parameters of the operation, one flag per parameter              |
| global options | `--env demo`, `--jq '.[]'`                | Available on every command; see [Global options](/cli/reference/global-options) |

## Reading a synopsis

Every synopsis in this documentation uses the same notation.

| Notation           | Meaning                                                        |
| ------------------ | -------------------------------------------------------------- |
| `command`          | Type it exactly as shown.                                      |
| `<value>`          | A value you supply.                                            |
| `[--flag]`         | Optional. Anything not bracketed is required.                  |
| `a \| b`           | Choose one.                                                    |
| `[GLOBAL OPTIONS]` | Any flag from [Global options](/cli/reference/global-options). |

## Groups and actions

Commands are grouped by the resource they act on, and each command calls one Deel API operation: `adjustments create --invoice` calls `POST /adjustments/invoice`, and `jobs status --job_id <id>` calls `GET /jobs/{job_id}`. Batch commands carry a `-bulk` suffix, for example `adjustments create-bulk`.

Three groups are utilities rather than resources: `auth` manages the token, `job` polls one or more jobs by id, and `jobs` lists and retrieves jobs with pagination.

## Variants

Some actions expose several operations under the same name. `adjustments create` can create an invoice adjustment or a payroll adjustment, which are distinct API operations with different request bodies. A variant flag selects the operation:

```bash
deel adjustments create --invoice --input ...
deel adjustments create --payroll --input ...
```

Exactly one variant flag is required. Running the action without one, or with more than one, exits with a `usage.variant` error. Requesting `--help` without a variant prints the available variants and their operations:

```text
adjustments create — select a variant:

  --invoice       POST /adjustments/invoice  — Create a single invoice adjustment
  --payroll       POST /adjustments/payroll  — Create a payroll adjustment
```

## Help at every level

Each level of `--help` reveals more of the command's contract:

| Command                                           | Shows                                                                |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| `deel --help`                                     | Command groups and the global options                                |
| `deel <group> --help`                             | Actions in the group                                                 |
| `deel <group> <action> --help`                    | Variants, when the action has them                                   |
| `deel <group> <action> [--variant] --help`        | Usage line, action options, request body fields, and response fields |
| `deel <group> <action> [--variant] --help --json` | The same contract as JSON                                            |

Action-level help prints what generic usage output cannot: the request body fields, which are passed through `--input` rather than as flags, and the fields of the response `data`.

```text
Create a single invoice adjustment

USAGE  deel adjustments create --invoice [GLOBAL OPTIONS] [--input <body>]

REQUEST BODY (--input)
  type                   string   required [BONUS | COMMISSION | DEDUCTION | EXPENSE | OTHER | OVERTIME | TIME_OFF | VAT]  — Invoice adjustment category ...
  amount                 number   required — Monetary amount to apply ...
  contract_id            string   required — Unique Deel contract identifier ...
  ...

RESPONSE — data
  status                 string            — Current processing status ...
  adjustment_id          string            — Unique identifier returned for the created invoice adjustment ...
```

## Machine-readable contracts

Adding `--json` to an action-level `--help` prints the contract as a JSON document: the usage line, the path and query parameters, the request body kind and fields (including nested objects), the multipart file fields, and the response fields. AI agents and tools consume this instead of scraping the human help, which is why the [agent instruction block](/cli/agents/setup#add-the-instruction-block) tells an agent to run it before every new command.

```bash
deel jobs status --help --json
```

```json
{
  "command": "jobs status",
  "usage": "deel jobs status [GLOBAL OPTIONS] --job_id=<string>",
  "params": [
    { "name": "job_id", "in": "path", "type": "string", "required": true, "description": "Job identifier" }
  ],
  "body": { "kind": "none", "fields": [], "fileFields": [] },
  "response": {
    "kind": "object",
    "fields": [
      { "name": "job_id", "type": "string", "required": true },
      { "name": "status", "type": "string", "required": true, "enum": ["PENDING", "RUNNING", "SUCCEEDED", "FAILED"] },
      { "name": "items", "type": "array", "required": true, "properties": [ ... ] }
    ]
  }
}
```

The `body.kind` value tells the caller how to construct `--input`:

| `body.kind`  | Meaning                                                            |
| ------------ | ------------------------------------------------------------------ |
| `none`       | The operation takes no body                                        |
| `json`       | A JSON object; `fields` lists its properties                       |
| `json-array` | A JSON array; `fields` describes each item                         |
| `multipart`  | A multipart upload; text fields go in `--input`, files in `--file` |

## Request body skeletons

`--generate-input` prints a JSON skeleton of the request body with every field present and typed placeholder values, then exits without calling the API or requiring a token. Redirect it to a file, edit the values, and pass the file back with `--input`. Agents use the same skeleton to build bodies without guessing field names.

```bash
deel adjustments create --payroll --generate-input > body.json
# edit body.json
deel adjustments create --payroll --input file://body.json
```

**`body.json`**

```json title="body.json"
{
  "type": "",
  "title": "",
  "amount": 0,
  "vendor": "",
  "country": "",
  "contract_id": "",
  "description": "",
  "cycle_reference": "",
  "date_of_adjustment": "",
  "submitter_profile_id": 0,
  "should_move_to_next_cycle": false
}
```

For array bodies the skeleton contains one example item. For operations that also require file uploads, the required `--file` flags are printed on stderr so that stdout remains valid JSON.

## Version

```bash
deel --version
```

Prints `deel <version>`. The CLI also sends its version to the API in the `x-deel-cli-version` request header.

## Next steps

#### [Request input](/cli/usage/request-input)

Pass request bodies as shorthand, JSON, files, or stdin

#### [Command reference](/cli/reference/overview)

Every command with its flags, request fields, and response fields

> Build apps and integrations that extend and enhance the Deel services.