Skip to content
PocketCmd

Quick Start

This page takes you from a fresh install to a shell prompt: set the app password, add a server, test it and connect.

1. Set the app password

Section titled “1. Set the app password”

On first launch PocketCmd asks you to create an app password. It is mandatory: the app lock can’t be turned off, and the password is one of the two factors that protect your vault. It needs at least 12 characters with an uppercase letter, a lowercase letter, a number and a symbol.

On a phone, a short setup assistant follows:

  1. Unlock with fingerprint or face: choose Keep biometric unlock or Use password only. The step is skipped when no fingerprint or face is enrolled on the device.
  2. Your first connection: the same choices as Add Server below, plus Restore a backup if you are moving from another device. Skip for now goes straight to the home screen.

Settings › Run setup assistant runs it again. Settings › Replay tutorials only resets the short tours that appear the first time you open each screen.

2. Add a server

Section titled “2. Add a server”

A server in PocketCmd is a saved connection: host, credentials, protocol and options. On an empty home screen, tap Add your first server. Once you have servers, the New server row at the end of the server list does the same. On desktop you can also use Add… in the sidebar.

Add Server offers two ways in:

  • Import from Computer connects to a computer running pcmd, the PocketCmd Server command. The screen shows the two steps to run there: Install gives the command that installs the newest server release this version of the app can pair with (curl -fsSL https://pocketcmd.com/install.sh | sh -s -- --api 1), and Run & scan starts pcmd and prints the QR code to scan. Pairing a server this way requires Pro. pcmd sync imports the hosts from that computer’s ~/.ssh/config once and works on Free. See QR Code Pairing, SSH Config Import and Server Installation.
  • Manual Setup opens the server form. The rest of this page uses it.

Free keeps one saved server. With one already saved, adding another opens the upgrade sheet. See Free and Pro.

3. Enter the connection details

Section titled “3. Enter the connection details”
Field Example
Display Name web-01
Hostname 192.168.1.100 or example.com
Port 22
Username deploy

If you already have an ssh command for this host, type its arguments into the field at the top of the form, for example -p 2222 -A [email protected]. PocketCmd fills in the username, host and port from it and -A turns on agent forwarding.

Group and Tags are optional. You can set them later.

4. Choose how to authenticate

Section titled “4. Choose how to authenticate”

Under Authentication, pick Password, SSH Key or None.

  • Password: enter it in the field. It is encrypted with your vault key before it is written to the device’s secure storage.
  • SSH Key: tap Use Saved Key to pick a stored key, or Add new key to Generate new key or Import existing key. You are asked for the passphrase if the key is encrypted.
  • None: only for servers that allow unauthenticated access.

Two-factor logins need no extra setup. When the server asks for a one-time code, PocketCmd prompts you for it, during the connection test and in the terminal. See Connecting.

5. Test and save

Section titled “5. Test and save”

Tap Test Connection. PocketCmd connects, authenticates and checks the host for Mosh, Eternal Terminal and tmux. Mosh and ET appear under Protocol only after a test finds them on the host.

Save runs the test first if you haven’t, and saves only when it passes. Save without testing stores the server as it is.

6. Connect

Section titled “6. Connect”

Tap the server on the home screen. PocketCmd opens a new terminal with the server’s saved protocol and tmux setting, and you get the shell prompt:

deploy@web-01:~$

Tap › next to the server, or long-press it (right-click on desktop), to open its server sheet: launch options, the server’s sessions, Files for SFTP, port forwards, and its workspaces and dashboards. See Home Screen.

Organizing servers

Section titled “Organizing servers”
  • Tags appear as chips at the top of the home screen. Selecting tags filters the servers, workspaces and dashboards together.
  • Groups share settings such as credentials and jump hosts among their servers. Create and nest them from a server’s Group field › Edit groups.
  • Archive a server from the ⋮ menu in its server sheet. Archived servers are hidden behind the Archived chip.
  • Each home section sorts from the button in its header, by Last used, Date added, Name or, for servers and workspaces, Latency.

See Server Organization for details.

Next steps

Section titled “Next steps”