The CLI Setu user manual

Overview and quick start

This manual covers the whole journey: installing and pairing, starting and managing sessions, running AI agents, touring the mobile app, notification and security settings, a full CLI command reference, and fixes for the problems people hit most often. Jump to any section from the list on the left, or read it top to bottom the first time.

The short version, if you like to learn by doing:

1. Install the companion

   On your computer, run npm install -g cli-setu. It needs Node.js 18 or newer on Windows, macOS or Linux.

2. Pair your phone

   Run cli-setu pair to show a QR code and scan it with the CLI Setu app. Each computer is paired once. Pairing does not start a terminal session.

3. Start a session and run an agent

   Run cli-setu session to start a terminal session, optionally with --cli claude or --cli codex to bridge that tool. It appears on your phone straight away.

Requirements

CLI Setu needs three things, and none of them are unusual:

• A computer running Windows, macOS or Linux with Node.js 18 or newer, to run the companion CLI. Windows is the platform we have tested end to end; macOS and Linux are supported by the CLI but have had less verification.
• An Android phone with the CLI Setu app installed from Google Play, to view and control sessions.
• Ordinary internet access on both devices, Wi-Fi or mobile data. The companion only makes outbound connections, so there’s nothing to open on your router or firewall, no SSH keys to manage and no VPN to configure.

Your computer needs to stay on and connected for its sessions to keep running, since your commands execute there, not in the cloud. Use your OS’s power settings if you’re kicking off a long agent run and want to be sure the machine doesn’t sleep.

Installing the companion

The companion is a single npm package. Install or update it with one command:

Confirm it worked:

macOS and Linux

Open Terminal (or your shell of choice) and run the install command above. If Node.js isn’t installed yet, get it from nodejs.org or a version manager like nvm first.

Windows (PowerShell or Windows Terminal)

Open PowerShell or Windows Terminal and run the same install command. If PowerShell blocks the npm command with an execution-policy error, that’s a shell setting, not a CLI Setu problem; running the command from Windows Terminal’s default profile usually avoids it.

WSL (Windows Subsystem for Linux)

If you do your development inside WSL, install the companion there instead of (or as well as) native Windows, so it can see the same project files and shell your terminal normally uses:

Pair and run sessions from inside WSL exactly as described below. A WSL install and a native Windows install are treated as separate computers, so pair whichever one you actually work in.

Pairing your phone

Pairing links one computer to your phone with a one-time key exchange. You only do it once per computer.

1. Run the pair command

   On your computer, run cli-setu pair. A QR code appears in your terminal. Pairing only pairs; it does not start a terminal session.

2. Open the app

   On your phone, open CLI Setu and tap “Add computer” (or the + on the home screen).

3. Scan the code

   Point your phone’s camera at the terminal. The app and the companion exchange keys directly; nothing is typed or copied.

4. You’re paired

   The computer appears in the app, and you’re ready to start a session with cli-setu session.

Pairing more than one computer: there’s no limit built into the flow. Run cli-setu pair on your work laptop, your home desktop, a cloud VM, wherever you work, and switch between them from the app’s home screen. Each computer keeps its own keys, so revoking one never affects the others.

Sessions

A session is one running terminal, tracked by the companion and mirrored to your phone. Start one whenever you want to work from your phone, or want a task to keep running after you’ve stepped away.

Starting: after pairing, run cli-setu session in the folder you want to work in. Running the bare cli-setu command only prints help; it does not start a session. To bridge a specific tool, add --cli claude or --cli codex.

Naming: sessions are labelled with their working folder and shell by default, so “shop-api: zsh” is easy to tell apart from “docs-site: bash” when you have several open.

Attaching: tap a session on your phone’s home screen to open it. You see the current screen and recent scrollback immediately, then live output as it happens.

Multiple sessions: open more than one at a time, on the same computer or across different paired computers, and swipe between them in the app. Start one for a long migration, another for a quick fix, another for an agent doing a refactor.

Detaching: just close the app or lock your phone. Nothing happens to the session. It’s still your terminal, still running on your computer.

To stop everything on a computer, run cli-setu stop there. This ends its sessions on that machine only; other paired computers are unaffected. Add a session id (from cli-setu status) to stop just one.

Using AI agents

Any AI coding agent that runs in a terminal works, because from CLI Setu’s point of view it’s just another program producing and reading text. Start a session, then launch the agent inside it as you normally would at your desk:

Each of these needs your own account or API key for that tool, set up exactly as it would be at your desk. CLI Setu doesn’t provide AI models or see your code; it only carries the terminal session to your phone, end-to-end encrypted.

The part that matters most from a phone is approvals. Coding agents constantly pause to ask permission before editing a file or running a command, and CLI Setu turns that into something you can act on with a thumb:

1. The agent asks for permission

   Claude Code, Codex, Gemini CLI or another agent wants to edit a file or run a shell command, and prints its usual prompt.

2. CLI Setu turns it into a card

   The app recognises the prompt and shows it as a card with the file or command, plus Approve and Deny buttons, instead of raw terminal text you’d have to parse.

3. You get a push notification

   If your phone is locked or the app is in the background, a notification tells you the agent is waiting, so you don’t need to keep the app open the whole time.

4. Tap, and it continues

   Tap Approve or Deny. The answer goes straight to the terminal, and the agent keeps working.

You can run several agents at once, one per session, on the same computer or across different paired computers, and jump between whichever one needs you next.

The mobile app, tour

A quick tour of what you’ll actually tap.

Home screen

Every paired computer and its open sessions, with a status dot showing online or offline. Tap a session to open it, or tap a computer to start a new one.

Session view

Your real terminal: full colors, scrollback you can scroll through, and text you can select and copy, sized to fit a phone screen without losing legibility.

Key bar

A row above the keyboard with Esc, Tab, Ctrl, arrow keys and shortcuts like Ctrl+C and Ctrl+D, since a phone keyboard doesn’t have them. You can reorder it and add your own snippets.

Custom commands

Save prompts and commands you send often, such as “Run the tests” or git status, in your own command palette. They're yours across every session and device, and one tap sends them to the session.

Diff viewer

When an agent edits a file, CLI Setu can show the change as a colored diff, additions and removals, formatted to read on a small screen, rather than a wall of raw patch text.

Notifications

Alerts for a finished task, an agent waiting for input, or output matching a keyword you chose. Covered in full below.

Settings

Notifications, Terminal (fonts and color themes), Security (app lock, session timeouts, device list) and Account (including deleting your account) all live under Settings.

Notifications

Turn these on (or off) individually in Settings → Notifications:

• Task finished: the foreground command in a session exits.
• Waiting for input: an agent (or any program) is blocked waiting for you to type or approve something.
• Keyword alerts: a notification fires whenever new output contains a word or phrase you’ve added, useful for watching a deploy log for “error” or a build for “done”.

Notifications are per-phone, so a second paired phone can be tuned differently, and they only ever describe what’s already visible in your own encrypted session.

Security settings

CLI Setu is end-to-end encrypted between your computer and your phone, and the security controls in the app are about limiting who can open it if your phone is lost, and which devices can see your sessions at all. See the security page for the full model; the practical settings are:

• App lock, in Settings → Security: require Face ID, fingerprint or a PIN before the app opens, on top of your phone’s own lock screen.
• Session timeouts: automatically lock the app after a period of inactivity, so a briefly unlocked phone doesn’t leave sessions exposed.
• Remove devices: unpair a computer from the computer itself with cli-setu unpair, or remove a device from the Devices tab in the app.

To close your account entirely, go to Settings → Account → Delete account in the app, or email support@evyasys.com. See the privacy policy for what deleting your account removes.

CLI command reference

Every companion command you’re likely to need, in one place.

Key bar and keyboard tips

The key bar above your phone’s keyboard exists because phone keyboards are missing keys that terminals lean on constantly. A few habits that help:

• Use Ctrl+C from the key bar to interrupt a stuck command, exactly as you would at a desk.
• Tab still completes paths and commands, which matters more, not less, when typing on glass.
• Arrow keys recall and edit command history, so you rarely need to retype a long command to fix a typo.
• Reorder the key bar or add your own snippet buttons (a common flag, a docker command, whatever you type often) from Settings → Terminal.

Troubleshooting

The QR code won’t scan

Make the terminal window bigger so the code renders larger, and check that the app has camera permission. If it still won’t scan, skip the camera: type the short code that cli-setu pair prints under the QR code into the app’s Devices tab.

My phone shows the computer as offline

Confirm the companion is actually running with cli-setu status, and that the computer is powered on, awake and connected to the internet. If it still shows offline, stop it with cli-setu stop and start a new session with cli-setu session.

Colors or characters look wrong

Set your terminal type to xterm-256color and make sure your shell is using a UTF-8 locale. In the app, you can also switch fonts and color themes under Settings → Terminal.

Notifications aren’t arriving

Check three things in order: that the relevant alert is switched on in Settings → Notifications, that CLI Setu has notification permission at the OS level on your phone, and that your phone’s battery optimization isn’t restricting the app in the background.

A session feels slow or laggy

This is almost always the network, not CLI Setu, since only text is sent. Try switching from a weak Wi-Fi signal to mobile data (or the reverse), and close sessions you’re not using.

npm install fails with a permission error

See the install permission tip above: install Node.js with a version manager like nvm rather than running npm install -g with sudo.

Updating and uninstalling

Updating the companion is the same command as installing it. Run it again whenever you want the latest version:

The mobile app updates through Google Play like any other app.

Uninstalling the companion removes it from that computer only; pairing on other computers is unaffected:

Before you uninstall, it’s worth running cli-setu unpair or removing the computer from the app if you don’t plan to reinstall, so it stops appearing in your paired-devices list.

Getting help

If this manual didn’t cover it, three good next stops:

• FAQ, for short, direct answers to the questions people ask most.
• Support, to reach a human, with your app version and computer OS handy so we can help faster.