Last updated

Undra CLI

The Undra CLI lets you drive your workspace from the terminal, so the same notes, plans, items, and search you use in the app can be scripted, piped into other tools, or handed to an AI.

Drive your running workspace from the terminal: list, create, search, and script it.

The CLI talks to your running Undra app over a local, token-authenticated bridge (loopback only, the same secured channel Undra’s own AI uses to act on your workspace). It does not open a port to the network and it never evaluates arbitrary code, it calls named actions on the live app.

The Undra app must be running

Every command reaches your workspace through the running app. If Undra is not open, commands fail fast with a clear message. There is no separate headless backend to start.

Install

On Windows, the installer adds undra to your PATH automatically, so a new terminal can run it straight away.

Verify it is wired up:

bash
undra doctor

doctor checks four things: the CLI runtime, that the app’s bridge metadata file exists, that the app answers a ping, and that a workspace is reachable. If any check fails, its line tells you what to fix (usually “open the Undra app”).

Quick start

bash
undra workspace info
undra --json items list type=note limit=10
undra --json search query="meeting notes"

Use --json whenever you are scripting or feeding another tool. Without it, output is pretty-printed for reading.

Commands

Workspace

bash
undra workspace info          # path + name of the active workspace
undra stats workspace         # item counts by type (and trash counts)

Items

bash
undra items list [type=note|plan|canvas|dash] [folder_path="Inbox"] [limit=100] [offset=0]
undra items create title="My note" [type=note] [raw_input="..."] [folder_path="Inbox"]
undra items get id="<itemId>"
undra items update id="<itemId>" [title="..."] [folder_path="Inbox"]
undra items delete id="<itemId>" [--yes]

items delete moves the item to the trash (recoverable). It asks for confirmation unless you pass --yes.

Notes

bash
undra notes write id="<itemId>" body="..." [title="..."] [mode=replace|append|prepend]

mode controls how body combines with the existing note: replace (default), append, or prepend.

bash
undra folders list                       # folders that contain items
undra search query="deep work" [k=20]    # semantic (vector) search

folders list is derived from your items, so a folder with no items in it will not appear. search is semantic and uses the same vector index as the in-app search, so it needs Undra’s AI features to have indexed your workspace first, otherwise it returns no matches.

App control

bash
undra app status                                  # app version + window state
undra app commands [filter="view"]                # list command-center commands
undra app command id="app.command_palette.open"   # run a command by id
undra app screenshot path="C:/tmp/undra.png" [format=png|jpeg]

Global flags

  • --json — machine-readable output for automation.
  • --verbose — include error details.
  • --timeout=<ms> — how long to wait for the app to respond (default 30000).
  • --dry-run — print the intended write action without executing it.
  • --yes / --force — skip the confirmation prompt for destructive writes.

Recipes

Preview, then create

bash
undra --dry-run items create title="CLI Smoke" type=note
undra items create title="CLI Smoke" type=note

Discover and run an app command

bash
undra app commands filter="palette"
undra app command id="app.command_palette.open"

Scriptable, JSON-piped query

bash
undra --json items list type=plan limit=50 | jq '.data[].title'

Troubleshooting

  • “Undra is not running” / “Could not reach the Undra app bridge”: open the Undra app, then retry. The CLI needs the running app.
  • “The Undra window is not available”: the app is running but its main window is closed or minimized to the tray. Open the window and retry.
  • “automation token was rejected”: the app restarted and minted a new token. Just retry, the CLI re-reads it.
  • undra not recognized (Windows): open a new terminal after install so the updated PATH is picked up.
  • undra doctor gives a one-shot snapshot of all of the above.

Not yet available

A few actions are not exposed to the CLI yet and report a clear “not available” message: switching the active workspace, restoring or duplicating items, permanent delete, reading a note’s body, creating/renaming/deleting folders, and storage stats. They are planned, but for now use the app for those.