Security and permissions

The CLI authenticates with a personal access token, so it is not a separate integration with its own identity. Every command runs as the person who created that token, with exactly that person’s permissions.

This matters more for the CLI than for most tools, because the commands write to payroll data. What follows is what that means in practice, then the protections the CLI applies and the responsibilities that remain with you.

What this means for you

Action attribution

An adjustment created from the CLI is indistinguishable from one created in the Deel app. It carries your name, appears in the same approval queues, and lands in the same audit records.

Treat the description field as customer-facing text, not an internal note: it appears on invoices and in audit history visible to both parties.

Permissions

The CLI grants no access of its own. It calls the same API the Deel app calls, subject to the same role checks. If you cannot do something in the Deel app, the CLI returns a 403 rather than doing it.

The practical consequence: a command that works for a colleague may fail for you, and the fix is a role or scope change in Deel, not a CLI setting. Those failures surface with the operation’s own error code in the envelope, not as a CLI error.

Token scopes narrow this further. A token is issued with a set of scopes, and a command needs the scope covering its endpoint. A token that can read contracts cannot necessarily write adjustments against them.

Confirm which identity you are using

Before running anything that writes, check who the CLI is acting as:

deel auth status

{
  "data": {
    "valid": true,
    "source": "keychain",
    "token": "****f4a2",
    "identity": {
      "id": 482915,
      "email": "jane.doe@example.com",
      "full_name": "Jane Doe",
      "profile_type": "client",
      "organization_id": 91043,
      "organization_name": "Acme Corporation"
    }
  }
}

• identity is the account the command will act as, and whose name will appear on the records it creates. It also names the organization, which matters if your token could resolve to more than one.
• source is stdin, env, or keychain. This is how you catch a stale DEEL_TOKEN shadowing the token you logged in with, which is the most common cause of “why did that run as the wrong person”. The environment takes precedence over the keychain, so an exported variable silently wins.

Tokens in automation

A token used in CI acts as whoever created it.

• Attribution. Scheduled adjustments will show that person’s name indefinitely, which is misleading once someone else owns the automation.
• Continuity. If that person leaves or their role changes, the automation breaks.

For anything recurring, use a token belonging to an account that represents the integration rather than an individual, scoped to only the endpoints the job needs.

Token handling

The CLI persists exactly one secret, and only in the OS keychain.

• Tokens are read from the sources and order in Token sources. Only the keychain persists a token; the other sources are used for the current process and discarded.
• deel auth login validates a token against the API before storing it and stores it per environment. deel auth logout removes it.
• Output masks tokens to their last four characters. Logs record the Authorization header as Bearer ***.
• The CLI never prompts for a token except in deel auth login on an interactive terminal, and the prompt hides the input.

Transport

Every request is HTTPS, and no flag changes that.

• The API base URL must be HTTPS. A non-HTTPS URL is rejected with config.baseurl, and a request that would carry credentials to a non-HTTPS address is refused with network.insecure.
• Certificate verification is always on, with no flag to disable it. See Corporate networks and private CAs for trusted roots and proxy setup.
• Every request carries an x-request-id header generated by the CLI and the x-deel-cli-version header. Mutating requests carry an Idempotency-Key so that retries cannot duplicate a write.

Local data

The only files the CLI writes are its own logs.

• The local log records request metadata only, with the query string omitted. Response bodies are logged only when you opt in, and are redacted. See Logging and privacy.
• Log files are created with owner-only permissions (0700 for the directory, 0600 for the file).
• The CLI sends no telemetry and contacts no host other than the selected API environment.

Release integrity

Each release is checksummed and signed, and the installer verifies both.

• Each release publishes SHA256SUMS, a Sigstore bundle, and the signing public key. The installer verifies the checksum on every install and the signature when cosign is present; DEEL_REQUIRE_COSIGN=1 makes the signature check mandatory. See Verify a downloaded binary.
• The source is published under the MIT license at github.com/letsdeel/deel-cli. Vulnerabilities can be reported through the repository’s security policy.

What you are responsible for

• Scope tokens to the operations you need. A token stored in the keychain grants every process running as your user the same access.
• Keep DEEL_TOKEN out of shell history and shell profiles on shared machines; prefer the keychain or --token-stdin.
• Treat --log-bodies output and any file you write with --input file:// as sensitive data.
• Pin the CLI version in automated environments and verify downloads.
• Give each AI agent its own token with the narrowest scopes, keep it in the demo environment until its workflow is proven, and review the local log after a session. See Agent workflows.

Next steps