Jump CLI command reference#

This page lists Jump CLI commands and flags. To install Jump CLI and sign in, see Get started with Jump CLI. For the MCP server, see Jump CLI MCP server.

Applies to#

Jump CLI on Windows, macOS, and Linux.
auth, config, tokens, connect, viewer, mcp, doctor, and version work with any Jump Desktop account.
team commands require a Jump Desktop for Teams team, the Admin or Admin (Read-Only) role on it, and an API token.

Conventions#

Arguments in angle brackets, such as <device-id>, are required. Arguments in square brackets, such as [team-id], are optional.
Lists of IDs are comma-separated with no spaces: --users id1,id2.
To display help for a command, run jump-cli <command> --help.

Global flags#

These flags apply to every command.

Flag	Value	Default	Description
`--json`	none	off	Print output as JSON instead of a table.
`--profile`	profile name	`JUMP_PROFILE`, otherwise `default`	Use this profile's tokens and settings. See Profiles.
`--help-ai`	none	off	Print the command overview for AI agents.
`--team`	team ID	the stored default team	Run the command against this team.
`--log-level`	`debug`, `info`, `warn`, `error`	`warn`	Logging level.
`--logfile`	path	`~/.jump-cli/logs/jump-cli.log`	Path of the log file.
`-h`, `--help`	none	off	Print help for the command.

jump-cli --update checks for and installs the latest version through the package manager. A copy installed with --user cannot update itself; rerun its installer.

Profiles#

Profiles keep separate tokens and settings on one computer. Choose a profile with --profile <name> or JUMP_PROFILE; the flag takes precedence. With neither set, Jump CLI uses default. JUMP_TOKEN and JUMP_TOKEN_FILE still take precedence over the profile's saved tokens.

jump-cli --profile work auth viewer login
jump-cli --profile work team select <team-id>

Names use letters, digits, hyphens, and underscores, and are case-insensitive. A profile is created when you first sign in or save a setting under it. See config profiles to list profiles and config remove-profile to delete one.

Output and exit status#

Tables are written to standard output. With --json, the same data is printed as JSON.
--help prints to standard output. Errors, prompts, and logs are written to standard error.
On success, the command exits with status 0. On any error, the command prints the error to standard error and exits with status 1. Server errors include the HTTP status, an error code, and a detail message, for example API 400 validation-error: <detail>.

Authentication#

Commands select a token in this order: the JUMP_TOKEN environment variable, then the file named by the JUMP_TOKEN_FILE environment variable, then an unexpired saved API token, then (for viewer status and mcp only) a saved viewer token. Jump CLI never accepts a token as a command-line argument.

Commands	Token needed
`team ...`, `tokens ...`	API token, `JUMP_TOKEN`, or `JUMP_TOKEN_FILE`
`connect bootstrap`	API token, `JUMP_TOKEN`, or `JUMP_TOKEN_FILE`, unless you pass `--code`
`viewer status`, `mcp`	Viewer token, API token, `JUMP_TOKEN`, or `JUMP_TOKEN_FILE`
`auth ...`, `config show`, `doctor`, `version`	None

In an interactive terminal, a command that requires an API token signs you in automatically when no usable API token is available, including when a saved token from auth api login has expired. When standard error is redirected, set JUMP_TOKEN or JUMP_TOKEN_FILE instead.

Environment variables#

Variable	Value	Description
`JUMP_PROFILE`	profile name	Select the profile; `--profile` takes precedence.
`JUMP_TOKEN`	token	Token to use instead of a saved token.
`JUMP_TOKEN_FILE`	path	File that contains the token to use instead of a saved token. On macOS and Linux, use mode `0600`; group read access is also accepted, but group write access and all access for other users are refused. `JUMP_TOKEN` takes precedence.
`JUMP_CLI_TOKEN_STORE`	`auto`, `keyring`, `file`	Where sign-in commands save tokens. `auto` (default) uses the operating system keyring, or `~/.jump-cli/credentials.json` when the keyring is unavailable or that token is already saved in the file. `keyring` uses only the keyring and fails if it is unavailable. `file` always uses the file. The file store is not available on Windows. See Token storage.

HTTP proxies and relay connections#

Jump CLI can use TCP or TLS relays when UDP connections are blocked. Remote sessions honor HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, including their lowercase forms.

TCP relays use HTTP_PROXY; TLS relays use HTTPS_PROXY.
Both HTTP and HTTPS proxy URLs are supported, including Basic authentication through credentials in the URL.
On a network that requires a proxy, the proxy must allow HTTP CONNECT to the relay.
Direct connections are still tried. If proxy setup fails, Jump CLI retries the TCP or TLS relay directly. These variables do not force every connection through the proxy.

Set the variables in the environment of the MCP client that launches Jump CLI. For example, on macOS or Linux:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

For the native Jump Desktop app's proxy settings, see Connect through a proxy.

auth#

Commands for signing in and out on this computer. Jump CLI saves tokens in the operating system keyring, or in ~/.jump-cli/credentials.json when the keyring is unavailable (see Token storage). Before a login command prints its sign-in URL, Jump CLI checks that it can store the token (for example, that ~/.jump-cli is writable when the file is used), then saves the token to the store it chose.

jump-cli auth api login

Signs in and saves an API token. The command prints a sign-in URL; open the URL in a browser and sign in. The browser does not open automatically, and the command waits up to 10 minutes. The token is valid for a few hours. If JUMP_TOKEN or JUMP_TOKEN_FILE is set, Jump CLI uses that token instead of this one.

With --json, the command prints one JSON line per step on standard output, as each step happens: a sign-in-url event, then a signed-in event. See Sign in from a script or AI agent.

auth api logout#

jump-cli auth api logout

Revokes and clears the saved API token. The viewer token is kept.

jump-cli auth viewer login

Signs in and saves a viewer token, which authenticates viewer status and mcp. The command prints a sign-in URL; open the URL in a browser and sign in. The browser does not open automatically, and the command waits up to 10 minutes.

With --json, the command prints one JSON line per step on standard output, as each step happens: a sign-in-url event, then a signed-in event. See Sign in from a script or AI agent.

auth viewer logout#

jump-cli auth viewer logout

Revokes and clears the saved viewer token. The API token is kept.

jump-cli auth login

Saves an API token you created in the Teams dashboard (Security > API Tokens). Paste the token when prompted.

auth logout#

jump-cli auth logout

Revokes and clears both the API token and the viewer token on this computer.

config#

config show#

jump-cli config show

Shows the current profile, default team ID, viewer account email, token status, automatic update setting, and update channel. API Token and Viewer Token appear as stored, expired, or not set. The output does not include JUMP_TOKEN.

config profiles#

jump-cli config profiles

Lists saved profiles and marks the current one.

config remove-profile#

jump-cli --profile <name> auth logout
jump-cli config remove-profile <name>

Deletes a profile's stored settings. Sign out first; removal is refused while the profile holds a token.

config set-auto-update#

jump-cli config set-auto-update on|off

Enables or disables automatic updates. By default, Jump CLI asks before updating. It checks at most once a day in an interactive terminal; startup checks are skipped for MCP, JSON output, and redirected input or output.

tokens#

Commands for server-side management of every viewer and API token on your account. These commands require an API token, JUMP_TOKEN, or JUMP_TOKEN_FILE.

tokens list#

jump-cli tokens list

Lists all your viewer and API tokens with their IDs.

tokens revoke#

jump-cli tokens revoke <token-id>

Revokes a viewer or API token by ID. To get token IDs, run tokens list.

connect bootstrap#

jump-cli connect bootstrap [flags]

Installs Jump Desktop Connect and adds a computer to your personal account or team. By default, it prints one comment and one command for you to review. The printed command runs Jump Desktop's official installer script, which checks signatures, installs Connect, and applies a Connect Code. For a walkthrough, see Set up a computer for remote access.

Flag	Value	Description
`--run`	none	Run the command instead of printing it. The installation may prompt for your `sudo` password; on Windows, run from an elevated (Administrator) prompt. If Connect is already installed, only the code is applied. Setup is refused for a computer that is already added to an account or team.
`--ssh`	`user@host`	Set up a host over SSH instead of this computer.
`--personal`	none	Add the computer to your personal account. Reuses your personal Connect Code, or creates a single-use code that expires after 1 hour.
`--team`	team ID	Add the computer to this team (global flag). In an interactive terminal, prompts you to select one of the team's installers; in other cases, pass `--installer`.
`--installer`	name or ID	Use this team installer and skip the prompt.
`--code`	Connect Code	Use this Connect Code as provided, without account lookups.
`--os`	`mac`, `linux`, `windows`	Set the host's operating system instead of detecting it.

Specify one mode: --personal, --code, or team (--team, --installer, or both). Combining modes causes an error.
Without a mode flag, an account with no team uses the personal account. An account with teams is shown the exact --personal and --team commands to choose from.
For a Windows host over SSH, Jump CLI always prints the command. Run it in an elevated PowerShell on the host.

viewer status#

jump-cli viewer status [--watch]

Shows whether each computer your account can access is online or offline. In a terminal, the table updates as results arrive for 5 seconds, and then the command exits. With --json or redirected output, the command prints once when the list stops changing, within 5 seconds.

Flag	Description
`-w`, `--watch`	Remain connected and update the output when a computer comes online or goes offline.

mcp#

jump-cli mcp [flags]

Runs the MCP server that enables AI agents to connect to and control your hosts. For details, see Jump CLI MCP server.

doctor#

jump-cli doctor [--offline]

Checks this computer's setup and reports each result: the Jump CLI version, the D-Bus session bus (Linux), the Secret Service, whether the keyring is unlocked, the file store, which credential Jump CLI will use, the connection to Jump Desktop, and the number of computers your account can access. The report never includes a token.

Flag	Value	Default	Description
`--offline`	none	off	Skip the connection check.

With --json, the report is printed as one JSON object. The command exits with a non-zero status if anything it found would stop Jump CLI from working. See Check your setup.

version#

jump-cli version

Prints the Jump CLI version.

team#

team commands require a Jump Desktop for Teams team, the Admin or Admin (Read-Only) role on it, and an API token. With the Admin (Read-Only) role or a read-only API token, only commands that do not change anything work (for example list, find, info, history, and billing). If you belong to one team, Jump CLI uses that team automatically. If you belong to several teams, select one with team select or pass --team <team-id>.

team list#

jump-cli team list

Lists the teams you belong to and their IDs.

team info#

jump-cli team info

Shows information about the active team.

team select#

jump-cli team select [team-id] [--clear]

Sets the default team. With no argument, lists your teams and marks the current selection.

Flag	Description
`--clear`	Clear the stored selection. A single-team account then selects its team automatically again.

Find commands#

team devices find, team users find, and team groups find take a regular expression (Go syntax) and match without regard to case. A plain word matches anywhere: find smith matches smith@example.com and "John Smith". To anchor a pattern, use ^ and $. Quote patterns that contain shell characters. Searches run only within the active team.

team devices#

Commands for the computers in the team. The Teams dashboard lists these computers under Computers.

team devices list#

jump-cli team devices list [--name <pattern>]

Lists the team's computers. --name filters by name on the server and accepts * as a wildcard (for example --name '*office*').

team devices find#

jump-cli team devices find <regex>

Finds computers by name. See Find commands.

team devices info#

jump-cli team devices info <device-id>

Shows the computer's name, operating system, version, last online time, and the users and groups with access to it.

team devices rename#

jump-cli team devices rename <device-id> --name <new-name>

Changes the computer's display name.

team devices urls#

jump-cli team devices urls <device-id>

Prints the computer's native (jump://), web, and screen-share connection links, and the link to its Teams dashboard page.

team devices disconnect#

jump-cli team devices disconnect <device-id> <session-id>

Ends one active session on the computer. Other sessions are not affected. To find session IDs, run team history connections --device <device-id>.

team devices delete#

jump-cli team devices delete <device-id>

Removes the computer from the team; the computer loses access immediately. The command asks you to confirm with y or yes, and any other answer cancels it. This action cannot be undone.

team devices installer#

Team installers are Connect Codes that add computers to the team.

team devices installer list#

jump-cli team devices installer list

Lists the team's installers.

team devices installer create#

jump-cli team devices installer create --name <name> [flags]

Creates an installer.

Flag	Value	Description
`--name`	text	Installer name. Required.
`--expiry`	seconds	Time until the installer expires. `0` means the installer never expires.
`--single-use`	none	The installer can be used only once.
`--require-auth`	none	Require authentication when connecting.
`--users`	user IDs	Users granted access to computers added with this installer.
`--groups`	group IDs	Groups granted access to computers added with this installer.

team devices installer delete#

jump-cli team devices installer delete <installer-id>

Deletes an installer.

team devices logs#

Diagnostic log bundles from a team computer.

team devices logs download#

jump-cli team devices logs download <device-id> [flags]

Requests a new bundle from the computer, waits for the upload to complete, and downloads the bundle as a zip file.

Flag	Value	Default	Description
`--output-zip`	path	`./JumpConnectDiagLogs-<device>-<request-id>.zip`	Path where the zip file is saved.
`--request-id`	request ID	none	Download an existing bundle instead of creating a new one.
`--timeout`	seconds	`60`	Time to wait for a new bundle. Ignored with `--request-id`.

team devices logs list#

jump-cli team devices logs list <device-id>

Lists the bundles still stored for the computer, with request ID, status, size, requester, and time until expiry.

team users#

team users list#

jump-cli team users list [--email <address>]

Lists team users. --email returns only the user with that exact email address.

team users find#

jump-cli team users find <regex>

Finds users whose email, first name, or last name matches. See Find commands.

team users info#

jump-cli team users info <user-id>

Shows the user's email, name, role, join time, and group and computer access.

team users set-role#

jump-cli team users set-role <user-id> --role <role>

Sets the user's role: admin, user, or admin-read-only.

team users remove#

jump-cli team users remove <user-id>

Removes the user from the team. The command asks you to confirm with y or yes, and any other answer cancels it. This action cannot be undone.

team users invite#

team users invite list#

jump-cli team users invite list

Lists pending invites.

team users invite create#

jump-cli team users invite create --email <address> [flags]

Creates an invite and sends it by email.

Flag	Value	Default	Description
`--email`	email address	none	Email address of the person to invite. Required.
`--name`	text	the part of the email address before `@`	Invite label.
`--devices`	device IDs	none	Computers the new user is granted access to.
`--groups`	group IDs	none	Groups whose access the new user receives.

team users invite delete#

jump-cli team users invite delete <secret>

Deletes an invite.

team groups#

Groups are Access Groups in the Teams dashboard.

team groups list#

jump-cli team groups list

Lists Access Groups.

team groups find#

jump-cli team groups find <regex>

Finds groups by name. See Find commands.

team groups create#

jump-cli team groups create --name <name>

Creates a group.

team groups rename#

jump-cli team groups rename <group-id> --name <new-name>

Renames a group.

team groups delete#

jump-cli team groups delete <group-id>

Deletes a group. The command asks you to confirm with y or yes, and any other answer cancels it. This action cannot be undone.

team groups members add#

jump-cli team groups members add <group-id> [--users <ids>] [--devices <ids>]

Adds users and computers to a group.

team groups members remove#

jump-cli team groups members remove <group-id> [--users <ids>] [--devices <ids>]

Removes users and computers from a group.

team access#

Commands for managing which users and groups can connect to a computer.

team access add#

jump-cli team access add <device-id> [--users <ids>] [--groups <ids>]

Adds users and groups to the computer's access list.

team access remove#

jump-cli team access remove <device-id> [--users <ids>] [--groups <ids>]

Removes users and groups from the computer's access list.

team access set#

jump-cli team access set <device-id> [--users <ids>] [--groups <ids>]

Replaces the computer's access list with these users and groups.

team access bulk-add#

jump-cli team access bulk-add --devices <ids> [--users <ids>] [--groups <ids>]

Adds users and groups to the access lists of several computers.

team access bulk-remove#

jump-cli team access bulk-remove --devices <ids> [--users <ids>] [--groups <ids>]

Removes users and groups from the access lists of several computers.

team annotations#

Key-value annotations on users, computers, and groups. The first argument is user, device, or group.

team annotations list#

jump-cli team annotations list <user|device|group> <target-id>

Lists annotations.

team annotations set#

jump-cli team annotations set <user|device|group> <target-id> --key <key> --value <value>

Sets an annotation.

team annotations delete#

jump-cli team annotations delete <user|device|group> <target-id> --key <key>

Deletes an annotation.

team history#

The same logs are available in the Teams dashboard; see Activity Logs and Connection Logs. Both history commands accept these flags:

Flag	Value	Default	Description
`--start`	time	none	Start of the period. Required.
`--stop`	time	now	End of the period.
`--csv`	none	off	Print output as CSV. Ignored when `--json` is set.

Times can be relative (7d, 24h, or 30m ago), a date (2024-01-15), a date and time ("2024-01-15 14:00"), or RFC 3339 with a time zone (2024-01-15T14:00:00Z).

team history audit#

jump-cli team history audit --start 7d

Shows the team audit log.

team history connections#

jump-cli team history connections --start 30d [--device <ids>]

Shows connection history. --device limits the history to one or more computers.

team billing#

Commands for viewing billing information. These commands are read-only.

team billing info#

jump-cli team billing info

Shows a billing summary.

team billing billable-users#

jump-cli team billing billable-users

Lists billable users.

team billing history#

jump-cli team billing history

Shows billing history.

team billing invoice#

jump-cli team billing invoice <history-id>

Prints the invoice URL for a billing history entry.

team billing ledger#

jump-cli team billing ledger

Shows billing ledger events.