Skip to content

CLI

Jump to bottom
meetsu edited this page Jul 11, 2026 · 3 revisions

CLI

The CLI is a separate accshift program you run from a terminal instead of the desktop app. It does the same things (list accounts, switch accounts) but from scripts, automation tools, or AI agents. The GUI and the CLI share the same accounts and settings, so changes in one show up in the other.

If you only use the desktop app, you can skip this page.

When to use it

  • Trigger an account switch from a script or a hotkey tool.
  • Pull the list of accounts into another program.
  • Run accshift on a machine without a GUI session.

Install

The CLI binary is built alongside the desktop app by pnpm tauri build:

  • Windows: target/release/accshift.exe
  • Linux: target/release/accshift
  • macOS: target/release/accshift

Drop it anywhere on your PATH, or call it by its full path.

Commands

accshift platforms               # list platforms this build supports
accshift list <platform>         # list accounts for a platform
accshift list <platform> --folder <name>   # filter by folder
accshift switch <platform> <account-id>    # sign in as that account

<platform> is one of the names printed by accshift platforms (for example steam, riot, epic).

Switch flags (Steam only)

--online | --invisible           # Steam start mode
--graceful | --force             # shutdown mode
--admin | --no-admin             # relaunch with admin rights
--launch-options "<string>"      # Steam launch options

If you do not pass a flag, the CLI falls back to whatever you set in the GUI for that option. Pass --launch-options "" if you want to override the GUI value with an empty string for one run.

Output format

The CLI auto-picks the format:

  • Running in a terminal: a readable table.
  • Output piped into another program or a file: a JSON envelope.

You can force JSON anywhere with --json. Errors always go to stderr, so the stdout stream stays clean for scripts.

JSON schema

{ "schema": "accshift.v1", "ok": true, "command": "list",
  "data": { "platform": "steam", "accounts": [ ... ] } }

{ "schema": "accshift.v1", "ok": false, "command": "switch",
  "error": { "code": "lock_contended", "message": "..." } }

Exit codes

The CLI sets a non-zero exit code on failure so scripts can branch on it:

Code Meaning
0 Success
1 Generic error
2 Platform not available on this OS or build
3 Unknown account
4 Another accshift process is already busy (see "Concurrency" below)
5 I/O error (paths, permissions)

Examples

List Steam accounts as a table:

$ accshift list steam
  ACCOUNT      PERSONA              STEAM ID
* alice        Alice                76561198000000001
  bob          Bob the Builder      76561198000000002
  carol        carol_gg             76561198000000003

3 accounts.  * = currently signed in

Switch to an account with Steam-specific overrides:

accshift switch steam bob --invisible --force --launch-options "-tcp -no-cef-sandbox"

Get strict JSON for a script:

accshift --json list steam | jq '.data.accounts[].account_name'

Concurrency

You can have the GUI and the CLI running at the same time. To stop them from stepping on each other, mutating commands (such as switch) take a short-lived lock. If another instance is already mid-operation, the second one exits with code 4 after a 2-second wait. Try again once the first one finishes.

Folder filter

--folder <name> matches the folder name as shown in the GUI sidebar. Matching is case-insensitive and includes nested subfolders. Without the flag, all accounts are listed.

Settings fallback

The CLI does not change GUI settings. For per-platform paths, API keys, or other options, set them once in the desktop app; the CLI picks them up automatically.

Deep links (accshift://)

Since 1.1.0 the desktop app also registers the accshift:// URL scheme, which covers the same scripting use case without a terminal:

accshift://switch/<platform>/<account>

<account> matches the account id first, then the username, then the display name (case-insensitive). Examples:

accshift://switch/steam/76561198000000002
accshift://switch/steam/bob
accshift://switch/riot/main%20smurf

Open one of these from a browser, a Stream Deck "Website" action, AutoHotkey's Run, or start / xdg-open in a script, and the app switches to that account (launching the app first if it is not running). URL-encode special characters (%20 for spaces).

Differences from the CLI:

  • The deep link drives the GUI, so you get the same toasts and visual feedback as a manual switch.
  • No output or exit code; for scripts that need to check the result, use the CLI.
  • Can be turned off in Settings > General > Integrations.
  • Links are ignored while the app is PIN-locked.

The scheme is registered by the installer, and the app re-registers it for the current user on every start (useful for portable builds).

Clone this wiki locally