Command structure

Every CLI invocation follows the same shape:

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

Reading a synopsis

Every synopsis in this documentation uses the same notation.

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:

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:

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:

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.

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 tells an agent to run it before every new command.

deel jobs status --help --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:

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.

deel adjustments create --payroll --generate-input > body.json
# edit body.json
deel adjustments create --payroll --input file://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

deel --version

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

Next steps