Auth and Contexts - Dify Docs

difyctl can hold sign-ins for several Dify hosts and accounts at once. Each host and account pair is a context: its metadata lives in hosts.yml in the config directory, and its bearer token lives in your OS credential store (with a sealed-file fallback). Each task maps to one command:

difyctl auth login signs you in to a host
auth whoami prints the identity you’re signed in as
auth list lists your saved contexts
auth logout signs you out of the active host
use host / use account switch the active context
auth devices list lists your active sessions
auth devices revoke revokes sessions you don’t recognize

For the step-by-step sign-in walkthrough, see Authenticate.

difyctl auth login [flags]

auth login runs the OAuth 2.0 device flow: it prints a one-time code and a verification URL, opens the URL in your browser, and waits for you to approve the sign-in there. The CLI never sees your password.

Flags

Flag	Type	Default	Description
`--host <url>`	string	none	The Dify host to sign in to. On self-hosted Dify, use the console API URL, since `difyctl` operates against the console API. A URL without a scheme gets `https://`. In a terminal, omit it and enter your host; in a non-interactive session (script, CI, pipe), the flag is required.
`--no-browser`	boolean	false	Don’t auto-open the browser; print the verification URL only.
`--insecure`	boolean	false	Allow `http://` hosts (local development only).

Examples

difyctl auth login --host https://dify.example.com

difyctl auth login --no-browser

Output

The code prompt goes to stderr, then a spinner waits for the browser-side approval:

! Copy this one-time code: WDJP-XKLM
  Open: https://dify.example.com/device

On success, the confirmation goes to stdout:

✓ Logged in to dify.example.com as <your-email> (<your-name>)
  Workspace: <your-workspace>

The Workspace: line is your default workspace. Each sign-in also registers a server-side session, labeled difyctl on <hostname>. Run auth devices list to see all your sessions. Signing in to a host you’re already signed in to refreshes that context’s stored token.

Exit Codes

Code	Meaning
`0`	Signed in
`1`	Network or server error
`2`	Usage error, such as a missing `--host` outside a terminal or a non-`https` host without `--insecure`
`4`	The sign-in was denied (`access_denied`), or the code expired before you approved it (`expired_token`)
`6`	The server has no device-flow sign-in endpoint (`unsupported_endpoint`)
`7`	Rate limited (HTTP 429)

See Output Formats and Exit Codes for the full scheme.

Check Your Active Identity

difyctl auth whoami [flags]

auth whoami prints who the active context belongs to. It reads the stored context without contacting the server, so it answers “which identity is active”, not “is the token still valid”. It exits 0 even if the session has expired server-side.

Flags

Flag	Type	Default	Description
`--json`	boolean	false	Emit JSON instead of the plain-text line.

Examples

difyctl auth whoami

For scripts:

difyctl auth whoami --json

Output

<your-email> (<your-name>)

The --json output is a single line with id, email, and name:

{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","email":"<your-email>","name":"<your-name>"}

Exit Codes

Code	Meaning
`0`	An active context exists
`4`	Not signed in (`not_logged_in`)

List Your Saved Contexts

difyctl auth list [flags]

auth list shows every stored host and account pair and marks the active one. Like auth whoami, it is purely local and never contacts the server.

Flags

Flag	Type	Default	Description
`-o <format>`	string	none	Output format: `json`, `yaml`, or `name`. Omit the flag for the default table.

Examples

difyctl auth list

Output

Format	What stdout gets
default	A table of your contexts: host, account, and an active marker.
`-o json`, `-o yaml`	A `contexts` array, each entry with `host`, `account`, `name`, and `active`.
`-o name`	The account emails, one per line.

Default table:

HOST                    ACCOUNT                      ACTIVE
dify.example.com        you@company.com (Your Name)  *
dify.internal.acme.com  you@acme.com (Your Name)

-o json:

{
  "contexts": [
    {
      "host": "dify.example.com",
      "account": "you@company.com",
      "name": "Your Name",
      "active": true
    },
    {
      "host": "dify.internal.acme.com",
      "account": "you@acme.com",
      "name": "Your Name",
      "active": false
    }
  ]
}

Exit Codes

Code	Meaning
`0`	Success, including when no contexts are stored
`2`	Usage error, such as an unsupported `-o` value

Sign Out

difyctl auth logout

auth logout revokes the active context’s session on the server, then deletes its token and hosts.yml entry from your machine. Other saved contexts are untouched. The local cleanup always happens. If the server-side revoke fails, difyctl prints a warning on stderr and clears your credentials anyway. The same applies when the token sits in an OS keychain that can’t be read at sign-out (locked, or no desktop session): the revoke is skipped and the local cleanup still runs.

Flags

None.

Examples

difyctl auth logout

Output

✓ Logged out of dify.example.com

Exit Codes

Code	Meaning
`0`	Signed out
`4`	Not signed in (`not_logged_in`)

Switch the Active Host

difyctl use host [flags]

use host changes which stored host subsequent commands run against. It is local: it only re-points the active context among the sign-ins you already have. To add a new host, run auth login --host instead.

Flags

Flag	Type	Default	Description
`--domain <host>`	string	none	The stored host to switch to, written as its bare domain (`dify.example.com`), without a scheme. In a terminal, omit it and pick from your stored hosts. In a non-interactive session (script, CI, pipe), the flag is required.

Examples

Switch to a stored host by its domain:

difyctl use host --domain dify.internal.acme.com

Output

On success, the new active host is confirmed:

✓ Active host is now dify.internal.acme.com

A domain you haven’t signed into fails as a usage error that lists your known hosts.

Exit Codes

Code	Meaning
`0`	Switched
`2`	Usage error: an unknown host, or a missing `--domain` outside a terminal
`4`	No stored sign-ins (`not_logged_in`)

Switch the Active Account

difyctl use account [flags]

use account changes which stored account is active on the current host. Like use host, it is local and only switches between sign-ins you already have.

Flags

Flag	Type	Default	Description
`--email <email>`	string	none	The account to switch to. In a terminal, omit it and pick from your stored accounts; in a non-interactive session (script, CI, pipe), the flag is required.

Examples

Switch to another account on the active host:

difyctl use account --email teammate-bot@company.com

Output

On success, the new active account is confirmed:

✓ Active account on dify.example.com is now teammate-bot@company.com

An email that isn’t stored on the active host fails as a usage error that lists your known accounts. An account whose stored token is gone (revoked, or cleared by a session revoke) fails with a not-logged-in error and a hint to sign in again.

Exit Codes

Code	Meaning
`0`	Switched
`2`	Usage error: an unknown account, or a missing `--email` outside a terminal
`4`	No stored sign-in on this host, or no credential for the chosen account

List Your Active Sessions

difyctl auth devices list [flags]

Every device-flow sign-in registers a server-side session, labeled difyctl on <hostname> by default. auth devices list shows the sessions active for your account so you can spot and revoke ones you don’t recognize.

Flags

Flag	Type	Default	Description
`--json`	boolean	false	Emit JSON instead of the table.
`--page <n>`	integer	1	Page number.
`--limit <n>`	integer	20	Page size, 1 to 200. The flag wins, then `DIFY_LIMIT`.

Examples

List the sessions active for your account:

difyctl auth devices list

Output

DEVICE                        CREATED               LAST USED             CURRENT
difyctl on Yours-MacBook-Pro  2026-06-02T09:14:31Z  2026-06-11T08:02:17Z  *
difyctl on build-runner-3     2026-05-28T11:40:09Z  2026-06-10T22:51:44Z

The table marks the session your current sign-in uses with *. LAST USED is empty for a session you haven’t used since signing in. --json prints a single line of JSON: a data array with one entry per session, plus the paging fields page, limit, total, and has_more. Each entry carries id, prefix, client_id, device_label, created_at, last_used_at, and expires_at.

Exit Codes

Code	Meaning
`0`	Success
`1`	Network or server error
`2`	Usage error, such as `--limit 0`
`4`	Authentication failure
`7`	Rate limited (HTTP 429)

Revoke Sessions

difyctl auth devices revoke [<target>] [flags]

auth devices revoke ends sessions server-side. The target matches by exact label first, then by exact session ID, then by case-insensitive label substring. A target that matches more than one session fails with the candidates listed, so pass an exact ID to disambiguate. In a terminal, difyctl first asks you to confirm (Revoke <N> session(s)? [y/N]); pass -y/--yes to skip the prompt. Outside a terminal (a script or pipe), it revokes without prompting. If you revoke the session your current sign-in uses, difyctl also clears that context’s local credentials: you are signed out on this machine.

Arguments

<target>: a device label or session ID from auth devices list. Required unless --all is passed.

Flags

Flag	Type	Default	Description
`--all`	boolean	false	Revoke every session except the current one.
`-y, --yes`	boolean	false	Skip the confirmation prompt.

Examples

Revoke one session by its label:

difyctl auth devices revoke "difyctl on build-runner-3"

Sign out everywhere else, keeping this machine’s session:

difyctl auth devices revoke --all

Output

On success, difyctl prints ✓ Revoked <N> session(s). A named target that matches nothing fails with no session matches "<target>". --all with no other sessions prints no sessions to revoke and exits 0.

Exit Codes

Code	Meaning
`0`	Revoked, or nothing to revoke under `--all`
`1`	Network or server error
`2`	Usage error: no target and no `--all`, an ambiguous target, no matching session, or declining the confirmation prompt
`4`	Authentication failure
`7`	Rate limited (HTTP 429)

See Output Formats and Exit Codes for the full scheme.

​Sign In

​Flags

​Examples

​Output

​Exit Codes

​Check Your Active Identity

​Flags

​Examples

​Output

​Exit Codes

​List Your Saved Contexts

​Flags

​Examples

​Output

​Exit Codes

​Sign Out

​Flags

​Examples

​Output

​Exit Codes

​Switch the Active Host

​Flags

​Examples

​Output

​Exit Codes

​Switch the Active Account

​Flags

​Examples

​Output

​Exit Codes

​List Your Active Sessions

​Flags

​Examples

​Output

​Exit Codes

​Revoke Sessions

​Arguments

​Flags

​Examples

​Output

​Exit Codes

Sign In

Flags

Examples

Output

Exit Codes

Check Your Active Identity

Flags

Examples

Output

Exit Codes

List Your Saved Contexts

Flags

Examples

Output

Exit Codes

Sign Out

Flags

Examples

Output

Exit Codes

Switch the Active Host

Flags

Examples

Output

Exit Codes

Switch the Active Account

Flags

Examples

Output

Exit Codes

List Your Active Sessions

Flags

Examples

Output

Exit Codes

Revoke Sessions

Arguments

Flags

Examples

Output

Exit Codes