Nana CLI

Nana CLI

The nana command talks to the server from a shell. It manages projects, terminal sessions, worktrees, and server settings. No desktop app is needed, so it also works on a Linux or macOS remote server and over SSH.

Commands work with what the server owns: projects and sessions. Tabs, panes, and workspaces belong to each app, so there are no commands for them. Browser tabs are the exception: they live in the desktop app, and nana browser talks to the app on this computer.

Install

  • With the desktop app: choose Install Command Line Tool… from the app menu. It adds the installation’s current directory to your user PATH, keeping the CLI, server, and runtime DLLs together across updates.
  • On a remote server: see Getting started.

Reopen your terminal after installing the command-line tool. An older standalone nana.exe earlier on PATH still takes precedence; remove that old copy if nana --version does not match the installed app.

Basics

nana .               # open this folder in the desktop app
nana project list    # list projects
nana --help          # all commands; nana <command> --help for details
  • Commands start the server they use if it isn’t running, including a remote one with --host. nana server status and nana server stop never start it.
  • Management commands take --json for machine-readable output.
  • Ending or discarding a session and deleting a project or worktree need --yes.
  • A project can be named by its ID, its name if unique, or its folder.
  • --host <destination> runs the command against the server on another computer. It must come first: nana --host devbox project list. See Remote servers.

Commands

Command What it does
nana Shows help.
nana <folder> Opens the folder as a project in the desktop app. Fails over SSH or without the desktop app.
nana server start|status|stop Starts, inspects, or stops the server. stop refuses while terminals run; add --force to end them.
nana project list|add|rename|set-color|set-icon|delete Manages projects. Deleting ends its terminals but keeps files on disk.
nana session list|create|send|send-keys|read-screen|history|search|wait|end|discard Creates terminals, sends input, reads output, and waits for text or exit.
nana worktree list|create|checkout-pr|register|remove Manages Git worktree projects, including checking out pull requests.
nana settings get|set Reads or changes server settings.
nana activity list|ack Reads or clears AI agent activity.
nana browser open|list|read|click|… Drives browser tabs in the desktop app on this computer. See Browser control.
nana exec <project> -- <program> [args] Runs a program in the project folder, without a shell.
nana git, nana files Run raw server Git and file actions as JSON. Advanced; the JSON shape follows the protocol and may change.
nana install-skills Installs the Nana CLI skill for the AI agents found in your home folder. --dir <path> adds another skills folder.
nana stdio Joins stdin and stdout to the server. Used by --host over SSH; you don’t run it yourself.

Sessions from a script

id=$(nana session create my-app)
nana session send "$id" "npm test"
nana session send-keys "$id" Enter
nana session read-screen "$id" --lines 20
nana session end "$id" --yes
  • send types text without pressing Return. send-keys sends Enter, Tab, Escape, Backspace, Ctrl+C, Ctrl+D, or Ctrl+Z.
  • read-screen returns the last visible rows. history and search page through scrollback as JSON.
  • --saved reads a session’s last saved screen, even after it ended.
  • end stops the program and keeps its saved output. discard also deletes the output.
  • Sessions created here outlive the command and appear in every app under Existing Terminals.
  • Inside a Nana terminal, session commands default to that terminal, and create to its project.
  • create can take a --directory and a command to run after --.
  • wait --text <text> waits for text on the screen, and wait --exit for the shell to exit. Both give up after 30 seconds by default.

Browser control

tab=$(nana browser open localhost:3000)
nana browser wait-for-navigation "$tab"
nana browser fill "$tab" "#email" "me@example.com"
nana browser click "$tab" "button[type=submit]"
nana browser wait "$tab" --text "Welcome"
nana browser read "$tab"
nana browser screenshot "$tab" | base64 -D > page.png
nana browser close "$tab"
  • Browser commands need the desktop app and don’t take --host. open starts the app if it isn’t running.
  • open prints the new tab’s ID. Pass it to the other commands.
  • snapshot lists a page’s interactive elements, each with a selector for click, fill, or type.
  • nana browser --help lists every command.

Exit codes

0 on success. On any error, nana prints nana: <message> to stderr and exits with 1, including when a program run with nana exec fails.

Profiles

NANA_DIR points the CLI, and the server it starts, at another profile folder. Use it to run a separate, throwaway server. See Server.

← Remote serversOverview →