Skip to content

CLI

Jump to bottom
meetsu edited this page Aug 5, 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

Windows (recommended): install the desktop app. The installer places accshift.exe next to the app and adds that folder to your user PATH, so accshift works in any terminal opened after the install. Uninstalling removes the PATH entry again. A standalone accshift-cli_<version>_x64.exe is also attached to each release if you want the CLI without the app; rename it to accshift.exe and put it anywhere on your PATH.

Linux: the deb/rpm packages install the CLI to /usr/bin alongside the app. A standalone accshift-cli_<version>_linux_x86_64 binary is also attached to each release. Building from source (pnpm tauri build) produces target/release/accshift.

macOS: the app bundle ships the CLI inside Accshift.app/Contents/MacOS/accshift. Symlink it onto your PATH:

ln -s "/Applications/Accshift.app/Contents/MacOS/accshift" /usr/local/bin/accshift

A standalone accshift-cli_<version>_macos_aarch64 binary is also attached to each release. Building from source produces target/release/accshift.

If the app's Settings > General > Integrations > CLI toggle is off, every list/switch command exits with code 7 and cli_disabled. Turn the toggle back on in the app to re-enable it.

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",
    "folder": null,
    "accounts": [],
    "current": null
  }
}
{
  "schema": "accshift.v1",
  "ok": false,
  "command": "switch",
  "error": {
    "code": "lock_contended",
    "message": "Another accshift instance is running. Retry once it finishes, or close the GUI."
  }
}

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)
6 PIN missing, unavailable, or incorrect
7 CLI disabled in Settings

Examples

List Steam accounts as a table:

$ accshift list steam
  ACCOUNT      NAME                 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.

Usage statistics

The CLI reads the same two switches as the app (Settings > Privacy). It reports one cli_command event per command, carrying the command name, whether it succeeded and a fixed error code on failure, never a platform account or an argument you typed. It never sends the daily ping, so a command you run five times counts as one person. With both switches off it starts no reporting at all. Details on the Anonymous analytics page.

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://)

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 a unique username, then a unique display name (case-insensitive). Ambiguous labels are rejected instead of selecting an arbitrary account. 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 installer or app bundle registers the scheme. On Windows and Linux the app also attempts current-user registration on startup, which covers development and portable builds. macOS registration comes from the bundle's Info.plist.

Clone this wiki locally