Get started with Jump CLI#

Jump CLI (jump-cli) is a command-line tool for automating Jump Desktop tasks from a terminal or script. It runs on Windows, macOS, and Linux. Most commands work with a personal Jump Desktop account, so a team is not required. Use Jump CLI to:

• Set up computers for remote access: install Jump Desktop Connect and add a computer to your personal account or your team with one command, either on this computer or on a host over SSH.
• Let an AI agent use your hosts: agents such as Claude Code and Codex use the MCP server in Jump CLI to connect to, view, and control the hosts your account can access. You monitor the sessions and take control in Mission Control.
• Manage a Jump Desktop for Teams team: find computers and users, check online status, and produce JSON output for automation.

To integrate Jump Desktop into your own software, use the REST API instead.

Install#

Follow the section for the operating system of the computer where you install Jump CLI. Each section is complete on its own: run its steps in order, then verify the installation.

macOS#

1. Install Homebrew if it is not already installed. The installer script uses Homebrew to install Jump CLI.

2. In Terminal, run:

   curl -fsSL https://jumpdesktop.com/downloads/install.sh | sh -s -- --component cli
   

Windows#

1. Install Scoop and git if they are not already installed. The installer script uses Scoop to install Jump CLI.

2. In a regular (not elevated) PowerShell window, run:

   $env:JUMP_COMPONENT = 'cli'; irm https://jumpdesktop.com/downloads/install.ps1 | iex
   

Debian or Ubuntu#

Use this section when your account has sudo access. Without sudo access, see Debian or Ubuntu without sudo.

1. Run:

   curl -fsSL https://jumpdesktop.com/downloads/install.sh | sh -s -- --component cli
   

The script adds the signed Jump Desktop APT repository and installs Jump CLI, so Jump CLI receives updates through your system package manager. After installing any missing prerequisites, the script refreshes only the Jump CLI package list. Installing a missing GnuPG prerequisite first requires refreshing all package sources. It retries slow downloads and prints its progress.

Debian or Ubuntu without sudo#

The --user option installs Jump CLI for your user account only, in ~/.local/bin, with no sudo access required. It is available only on Debian and Ubuntu, and only for Jump CLI.

1. Run:

   curl -fsSL https://jumpdesktop.com/downloads/install.sh | sh -s -- --component cli --user
   

2. If ~/.local/bin is not on your PATH, the script prints the export line to add. Add that line to your shell profile, then open a new shell.

3. Before it unpacks Jump CLI, the script verifies the package against the signed Jump Desktop repository: the repository signature against the pinned signing key, then the package index, then the package.

4. A user installation does not update itself. To update Jump CLI, run the same command again.
5. Setting the environment variable JUMP_USER_INSTALL=1 has the same effect as --user.

RHEL or Fedora#

1. Run:

   curl -fsSL https://jumpdesktop.com/downloads/install.sh | sh -s -- --component cli
   

The script adds the signed Jump Desktop package repository and installs Jump CLI, so Jump CLI receives updates through your system package manager. The same command also works on CentOS, Amazon Linux, and SUSE.

Verify the installation#

Run:

jump-cli version
jump-cli doctor --offline

jump-cli version prints the installed version. jump-cli doctor --offline checks where Jump CLI can store sign-in tokens on this computer; see Check your setup.

Sign in#

Jump CLI uses two types of token:

Each login command prints a sign-in URL. Open the URL in a browser on any device and sign in. Jump CLI never opens the browser itself, and the command waits up to 10 minutes for you to sign in. Before it prints the URL, Jump CLI checks that its token store is usable. If that check fails, for example because the file store is not writable, fix the reported problem and run the command again. For where tokens are stored, see Token storage.

• Tokens from auth api login are valid for a few hours. When run in a terminal, a command that requires an API token signs you in again automatically.
• To create a token in the Teams dashboard, go to Security > API Tokens and click Generate new token. Dashboard tokens do not expire by default and can be read-only. To save a dashboard token, run jump-cli auth login and paste the token when prompted. For scripts and CI, set JUMP_TOKEN or JUMP_TOKEN_FILE instead; see Tokens from the environment.
• Jump CLI never accepts a token as a command-line argument.
• To view the tokens saved on this computer, run jump-cli config show. The output does not include JUMP_TOKEN.

To sign out of both tokens on this computer, run jump-cli auth logout. To list the tokens on your account, run jump-cli tokens list; to revoke one, run jump-cli tokens revoke <token-id>.

Sign in from a script or AI agent#

Add --json to jump-cli auth viewer login or jump-cli auth api login to receive each step as one line of JSON on standard output. Each line is written as soon as the step happens, so a script or agent can show the URL to a person and then wait for the result:

{"event":"sign-in-url","url":"<sign-in-url>","scope":"viewer","expiresAt":"<RFC 3339 time>"}
{"event":"signed-in","scope":"viewer","email":"<your-email>","saved":true}

expiresAt is the time at which the command stops waiting for the sign-in. An AI agent signing in for you prints the url value, asks you to open it, and waits for the signed-in line with saved: true and a successful command exit. API sign-in uses scope api-all and also reports tokenExpiresAt when the token has an expiry. If saving fails, API sign-in can report saved: false and the command exits with an error.

Token storage#

Jump CLI stores tokens in the operating system keyring. On Linux, the keyring is the Secret Service on the D-Bus session bus. Headless servers, containers, and SSH sessions often have no session bus or Secret Service, or keep the keyring locked.

When the keyring is unavailable, Jump CLI stores tokens in ~/.jump-cli/credentials.json and prints a warning. Only your user account can read this file (mode 0600, in a directory with mode 0700), the same protection as an SSH private key; the file is not encrypted. Jump CLI refuses a credentials file that other users can access, or a directory that other users can write to, and prints a chmod command to fix the permissions. The file store is not available on Windows.

In the default auto mode, a token saved in the file stays there: later sign-ins for that token type update the file, including from a desktop session where the keyring is available. Sign-out attempts to clear both stores. If the keyring cannot be reached, Jump CLI warns that a token saved there was not removed; sign out from that session too.

To choose the store, set JUMP_CLI_TOKEN_STORE:

Tokens from the environment#

For scripts, CI, and containers, supply a token without signing in:

• JUMP_TOKEN: the token itself.
• JUMP_TOKEN_FILE: the path to a file that contains the token. On macOS and Linux, use mode 0600 (owner read and write only). Group read access is also accepted for shared secret mounts; group write access and all access for other users are refused.

Jump CLI uses the first token it finds, in this order: JUMP_TOKEN, then JUMP_TOKEN_FILE, then saved tokens. An unreadable or invalid token file stops the command rather than falling back to a saved token. If authorization errors occur after you sign in, verify that JUMP_TOKEN and JUMP_TOKEN_FILE are not set to an outdated token.

Check your setup#

jump-cli doctor checks whether Jump CLI can work on this computer and reports each result:

• The Jump CLI version.
• On Linux, the D-Bus session bus, the Secret Service, and 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.

jump-cli doctor              # human-readable report
jump-cli doctor --json       # the same report as one JSON object
jump-cli doctor --offline    # skip the connection check

The report never includes a token. The command exits with a non-zero status if anything it found would stop Jump CLI from working.

Sign in on a headless Linux server, container, or SSH session#

On a Linux computer with no desktop session, sign-in may report that the keyring is unavailable or locked. To resolve it:

1. Run jump-cli doctor --offline to see which check fails.
2. Choose one of these options:
   • Use the file store. With the default JUMP_CLI_TOKEN_STORE=auto, Jump CLI saves the token in ~/.jump-cli/credentials.json when the keyring is unavailable. Run jump-cli auth viewer login (or jump-cli auth api login) and accept the warning. To skip the keyring entirely, set JUMP_CLI_TOKEN_STORE=file.
   • Supply the token from a file. Store a token in a file that is not group-writable or world-readable, and set JUMP_TOKEN_FILE to its path. See Tokens from the environment.
   • Use the keyring. Optional. Start a D-Bus session bus (for example with dbus-run-session or dbus-launch) and an unlocked keyring in it, for example gnome-keyring-daemon --unlock --daemonize --components=secrets, which reads the keyring password from standard input. Run Jump CLI in the same session.
3. Run jump-cli doctor again. It confirms which credential Jump CLI will use and that it can connect to Jump Desktop.

Set up a computer for remote access#

jump-cli connect bootstrap installs Jump Desktop Connect and adds the computer to your account, so you can connect to it when no one is at the computer (see unattended access). By default, it prints a single command for you to review. To run the command instead, add --run.

jump-cli connect bootstrap --personal --run                 # this computer, your personal account
jump-cli connect bootstrap --personal --ssh user@host        # a Mac or Linux (alpha) host over SSH
jump-cli connect bootstrap --team <team-id>                 # pick one of the team's installers

• If your account has no team, the computer is added to your personal account. If you belong to a team, Jump CLI shows the exact --personal and --team commands so you can choose between them.
• --personal reuses your personal Connect Code, or creates a single-use code that expires after 1 hour.
• The printed command runs Jump Desktop's official installer script, which checks signatures, installs Connect, and applies the code. The installation may prompt for your sudo password.
• With --run, 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.
• For a Windows host over SSH, Jump CLI always prints the command; run the command in an elevated PowerShell window on the host.
• On a Mac host, a person at the Mac must still grant Connect its macOS permissions.

Check your computers#

To view the online status of your personal and team computers, run:

jump-cli viewer status            # online or offline status of your computers
jump-cli viewer status --watch    # keep updating

Use Jump CLI with AI agents#

jump-cli mcp runs an MCP server that enables an AI agent to connect to and control the hosts your Jump Desktop account can access. For details, see Jump CLI MCP server. For restricted networks, see HTTP proxies and relay connections.

Before you start#

• Each host must have Jump Desktop Connect installed, and your Jump Desktop account must have access to the host.
• On a Mac host, a person at the Mac must grant Connect its macOS permissions. Without the Screen Recording and Accessibility permissions, the agent cannot view the screen or control the mouse and keyboard.
• Jump CLI must be installed on the computer that runs your MCP client. See Install and follow the section for that computer's operating system.

Set up#

1. Sign in with jump-cli auth viewer login. To restrict the agent to viewer access, see Security. When an agent runs the sign-in for you, it can add --json; see Sign in from a script or AI agent. On a headless Linux computer, see Sign in on a headless Linux server, container, or SSH session.

2. Add Jump CLI as an MCP server in your agent:

   Claude CodeCodex CLI

   claude mcp add jump-cli -- jump-cli mcp
   

   codex mcp add jump-cli -- jump-cli mcp
   

   To configure OpenCode, Cline, Continue, Goose, Zed, and other clients, see Add the server to an MCP client.

3. Ask the agent to list your computers and connect to one. If the agent returns the list, the setup is working.

Watch and take over with Mission Control#

Mission Control is a local web dashboard for monitoring agent sessions live. It runs on the computer that runs your MCP client. To open Mission Control, ask the agent for its link. The link contains an access key, so keep it private. The agent can work on up to 8 hosts simultaneously.

• On a session's page, Activity lists each action the agent takes.
• When the agent requests a password, enter the password in Mission Control rather than in chat; the password is not sent to the agent.
• To use the host yourself, click Take control. When you finish, click Give back control.

For details, see Mission Control.

For the actions an agent can perform, see Jump CLI MCP server.

Security#

An agent connected through Jump CLI can perform any action available to the signed-in user on the host. Before you connect an agent:

• Use only a viewer token. An API token also permits team administration. Run jump-cli auth api logout, do not set JUMP_TOKEN or JUMP_TOKEN_FILE for the MCP client, and then run jump-cli auth viewer login.
• Restrict the hosts the account can access, for example with a separate Jump Desktop account or, on a team, with Access Groups.

For the full checklist, see MCP server security.

Manage a team#

team commands require a Jump Desktop for Teams team, the Admin or Admin (Read-Only) role, and an API token. The Admin (Read-Only) role can run only commands that do not change anything. If you belong to several teams, select one:

jump-cli team list                  # list your teams and their IDs
jump-cli team select <team-id>      # set the default team

To run a single command against a different team, add --team <team-id>.

For machine-readable output, add --json to any command:

jump-cli team devices find '^office-'       # computers whose names start with "office-"
jump-cli team users list --json             # users as JSON

The command reference documents every team command, including the commands for users, Access Groups, access lists, history, and billing.

Next steps#

• Jump CLI command reference
• Jump CLI MCP server
• Let AI agents control computers
• Check in on AI agents and long-running work
• Set up unattended access
• Get started with Jump Desktop for Teams