Skip to main content

​
Renew Your Sign-In

A sign-in lasts 14 days (on a self-hosted server, adjustable with OAUTH_TTL_DAYS), and using difyctl doesn’t extend it. After that, every command that uses your sign-in fails with auth_expired (exit code 4) until you sign in again. To see when yours expires, check expires_at in your sessions.
On a self-hosted server, ACCESS_TOKEN_EXPIRE_MINUTES and REFRESH_TOKEN_EXPIRE_DAYS don’t change how long a difyctl sign-in lasts.
To renew it, run login again. It signs you out first, then starts the new sign-in. If the new sign-in fails, you stay signed out until one succeeds.

​
Use Several Servers or Accounts

Each config folder holds one sign-in, and a new sign-in replaces it. To switch servers, run login with the new --server. To switch accounts, run login and approve it in a browser signed in to Dify as the other account. To stay signed in to several at once, give each sign-in its own folder with DIFY_CONFIG_DIR, and set it on every command that uses it:
Two folders can’t hold separate sign-ins to the same server with the same account on one machine: signing in from one ends the other’s session.

​
Switch Your Workspace Cloud

To work in another workspace, find its id in the list of your workspaces, then switch to it:
The switch applies only to this difyctl sign-in, and Dify in your browser keeps its own workspace. To see which workspace difyctl is in, run difyctl describe workspace.
Two things override the switch:
  • Signing in again moves difyctl back to the workspace you approve the sign-in in.
  • If DIFY_WORKSPACE_ID is set, difyctl works in that workspace and use workspace fails. Unset the variable to switch.
To run a single command in another workspace without switching, add --workspace-id:
Commands that take an --app-id find the app in any of your workspaces, so they don’t need --workspace-id. The exceptions are check console_app dsl and import console_app dsl: for an app in another workspace, add its --workspace-id.

​
Where Your Token Lives

difyctl keeps your token in the OS keychain, under the service name difyctl: Keychain on macOS, Credential Manager on Windows, and Secret Service on Linux. It writes the token to tokens.yml in the config folder instead, when:
  • You sign in with --no-keyring.
  • You’re on Linux with no desktop session bus (DBUS_SESSION_BUS_ADDRESS is unset).
  • The keychain can’t be used when you sign in.
Keep tokens.yml out of container images, backups you share, and version control.
The config folder is:
  • macOS: ~/.config/difyctl
  • Linux: $XDG_CONFIG_HOME/difyctl, or ~/.config/difyctl if XDG_CONFIG_HOME is unset
  • Windows: %APPDATA%\difyctl
To use another folder, set DIFY_CONFIG_DIR.

​
Sign Out

To switch accounts, run login directly. It signs you out of the current account first.
Run logout when you’re done with a machine:
logout ends your session on the server and deletes your token and saved sign-in from this machine. If the server can’t be reached, logout still clears this machine, but the session stays valid on the server until it expires or you end it.

​
See and End Your Sessions

To see where you’re signed in, list your sessions:
Each session shows its id, the machine’s hostname as device_label, and when it expires as expires_at. To end a session on another machine, such as one you no longer have, delete it by ID. Pick it by device_label, so you don’t end the session on the machine you’re using.
To end the session you’re using right now, run logout instead: deleting it by ID leaves your saved sign-in behind, and your next command fails with auth_expired.
Last modified on October 28, 2026