Skip to content

Lionote CLI Guide

Lionote

About 2051 wordsAbout 7 min

CLIAI AgentAutomation

2026-08-27

Lionote CLI is a command-line tool included with the Lionote desktop app. It lets people, scripts, and AI agents with local terminal access read, search, create, and update local notes.

Download the Lionote Skill

Download Lionote SKILL.md

After downloading it, create a subdirectory named lionote and save the file as SKILL.md. Restart the agent or open a new agent session so it can load the Skill.

  • Codex on Windows: C:\Users\<username>\.codex\skills\lionote\SKILL.md
  • Codex on macOS/Linux: ~/.codex/skills/lionote/SKILL.md
  • Claude Code for the current project: <project>/.claude/skills/lionote/SKILL.md
  • Claude Code for all projects: ~/.claude/skills/lionote/SKILL.md

Other agents that support Agent Skills follow the same layout: <that agent's skills directory>/lionote/SKILL.md. The Skill only tells an agent how to call the CLI safely. You still need to download and install Lionote and make sure lionote-cli is available through your system PATH.

Get started

These instructions describe the desktop CLI on the 3.9.8 branch. The CLI supports note links and backlinks in note bodies, mind map nodes, and flowchart nodes, including querying, adding, and removing references.

Platform requirements

PlatformFirst-time setupWhile the app is runningWhile the app is closed
macOSEnable the CLI in Settings and register the terminal commandThe app handles CLI commandsThe app must start before commands can run; the launcher attempts to start it and wait until it is ready
WindowsInstall the desktop app and reopen your terminal or agentAutomatically connects to the app to execute commands and refresh notesReads and writes local notes independently without starting the app
LinuxInstall a desktop package containing the CLI and configure the command and PATHRuns independently and notifies the app to refresh after writesReads and writes local notes independently without starting the app

You do not need to install Dart or Flutter. After completing the setup for your platform below, open a new terminal and check:

lionote-cli --help
lionote-cli doctor --json

Call the command through your system PATH; do not hard-code an app installation path in a script or agent prompt. Reopen your terminal, Codex, or another agent session after installation or PATH changes.

macOS: enable the CLI and register your terminal

  1. Open Lionote and enable “Command line interface” in Settings.
  2. Select “Set up terminal command”, copy the setup command, and run it once in macOS Terminal. The one-time code expires in five minutes; get a fresh command from Settings if it expires.
  3. Reopen your terminal or AI tool and run lionote-cli doctor --json to verify.

On macOS, note commands are handled by the running Lionote app. Keep the app running with the CLI enabled. If the app is closed, the launcher attempts to start it and wait until it is ready. If startup or connection fails, open Lionote manually before trying again.

Setup creates the user-level command ~/.local/bin/lionote-cli and configures PATH for zsh or bash when needed. Follow the terminal instructions for other shells. Disabling the CLI revokes existing authorization; register the terminal command again after re-enabling it.

The macOS App Store version only accesses the app's current account and does not support --data-dir, --db, or --allow-other-library. Examples below that override the directory or database apply to the independent Windows/Linux CLI; omit those options on the macOS App Store version.

Windows: works with the app open or closed

The installer adds the actual installation directory to your user PATH. Reopen PowerShell or your agent, then run:

lionote-cli.exe doctor --json

No additional CLI setting is required on Windows. While the app is running, the CLI automatically connects to the current user's app, which saves the current edit, executes the command, and refreshes its views. While the app is closed, the CLI handles local notes independently. Successful writes do not require restarting Lionote.

Linux: install the command and check your environment

Use a package matching your system architecture (x64 or arm64). Release/Profile bundles that include the CLI provide lionote-cli and install-cli.sh. You can run the executable directly after extraction:

"/actual/install/directory/lionote-cli" doctor --json

To use the stable command name, run the installation script included in the bundle:

bash "/actual/install/directory/install-cli.sh"

By default, this creates a symbolic link at /usr/local/bin/lionote-cli, requesting permission through sudo if the directory is not writable. To install in your user directory instead:

LIONOTE_CLI_BIN_DIR="$HOME/.local/bin" bash "/actual/install/directory/install-cli.sh"

Before using the CLI:

  • Make sure ~/.local/bin is on your terminal or agent's PATH, then reopen the session.
  • Keep the installation directory in a stable location: the installed command is a symbolic link. Rerun the installation script after moving, deleting, or changing the bundle path.
  • If the extracted CLI is not executable, run chmod +x "/actual/install/directory/lionote-cli".
  • Run the CLI as the same system user that runs Lionote. Avoid sudo lionote-cli, which may select another user's configuration.
  • For first-time setup, open Lionote to configure the account and storage location, then verify them with doctor --json. The CLI can subsequently run while the app is closed. When the app is running, writes send a local refresh notification. Avoid editing the same note simultaneously in the app and CLI.

Data directory and database

The CLI defaults to the desktop app's configured storage location and current account. Start with automatic discovery:

lionote-cli doctor --json

On Windows/Linux, the database is usually db.json when signed out and <account>-db.json after signing in. The CLI checks the current account and does not select a database by modification time. If discovery fails, check the app's account and storage settings first.

When you need to explicitly select the current library on Windows/Linux, use the following options and recheck writeSafe and the actual storage target:

lionote-cli --data-dir "<Lionote data directory>" --db "<account>-db.json" list --json

Specifying a directory or database does not bypass account checks. The macOS App Store version follows the app's current account; omit these options there.

Check local status first

lionote-cli --version
lionote-cli capabilities --json
lionote-cli doctor --json

doctor reports the selected data directory, database, desktopRunning, and writeSafe. Use writeSafe to decide whether a write is allowed: only write when it is true. desktopRunning only reports whether the desktop app is running; it does not by itself block writes.

Common commands

Replace <noteId>, <parentNoteId>, and <Lionote data directory> with your own values. Scripts and agents should use command-level --json for machine-readable output and errors.

lionote-cli list --json
lionote-cli read <noteId> --json
lionote-cli search --query "meeting" --limit 20 --json

search checks note titles, summaries, and tags. Use read <noteId> --plain when you only need the plain text body.

Create a note

lionote-cli create --title "AI-generated note" --content "Note body" --json
lionote-cli create --parent <parentNoteId> --title "Child note" --content "Body" --json

For longer content, read from a file or standard input:

lionote-cli create --title "Imported content" --file "./note.md" --json

Update or append to a note

lionote-cli update <noteId> --title "New title" --json
lionote-cli update <noteId> --content "New body" --json
lionote-cli update <noteId> --append --content "Additional content" --json

update replaces the supplied body by default. Use --append to preserve the existing body. You can also pass longer content with --file "./note.md" or --file -.

Lionote stores native note references as lionote://<noteId>. Adding a reference makes the relationship available in both notes' related-note areas and the relationship graph. The target shows a backlink without inserting another link into its body. To make both bodies reference each other, add a second reference with the IDs reversed.

Use search and read to confirm real note IDs. Before writing, check that doctor --json returns writeSafe=true:

lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --text "Related material" --json
lionote-cli link list --id <noteId> --json
lionote-cli link remove --id <sourceNoteId> --target <targetNoteId> --json

By default, add inserts a Markdown reference into the source body, using the target title if --text is omitted. It does not insert duplicates when that body already references the same target. remove deletes references to the target from the source body. If a diagram node or the other note still contains a reference, the relationship remains and the result reports related=true. Both relationship entries are cleared only when neither direction has any references left.

link list is read-only and returns:

FieldMeaning
outgoingNotes referenced by the current note
incomingNotes referencing the current note; mutual references appear in both groups
locationsReference locations: area=body/mind/flow, with nodeId for diagram nodes
relationIdsThe saved semicolon-separated relationship set, also returned by read --json; this set does not encode direction

Each reference entry also includes the note's id and title. Direction is determined from actual body and diagram references in the current account, including historical backlinks missing from saved relationship metadata. Missing targets and notes belonging to another account are excluded from valid results.

References on mind map and flowchart nodes

Inspect the real node IDs before adding or removing a reference at a specific location:

lionote-cli diagram inspect --id <sourceNoteId> --nodes --json
lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --diagram mind --node <nodeId> --json
lionote-cli link remove --id <sourceNoteId> --target <targetNoteId> --diagram mind --node <nodeId> --json

mindMap.nodes and flowchart.nodes return each node's id, text, and link. Use --diagram mind for mind maps and --diagram flow for flowcharts, always together with --node. These commands only change the selected node's reference, preserving its text, position, and diagram edges. A node has one reference: adding a different target replaces that node's previous reference, while other nodes and body references stay intact.

Regular create, update (including append), and diagram writes also maintain relationships automatically. Use [label](lionote://<noteId>) in the body; the CLI does not resolve raw [[title]] text into a note reference. New relationships are only created for valid notes in the current account. Unresolved reference text is preserved.

The compatibility option --no-content-link only reconciles existing references with relationship metadata. add returns LINK_REFERENCE_REQUIRED when neither note contains a reference, and remove cannot disconnect notes that still reference each other. This option cannot be combined with diagram-node operations.

These extensions require an updated CLI with protocolVersion 6 or later in --version --json. Scripts can discover lionote_list_note_links, lionote_add_note_link, and lionote_remove_note_link through capabilities --json. On Windows, a running App executes commands and refreshes its views; when the App is closed, the CLI runs independently. Successful writes do not require restarting the App.

Additional operations

The CLI can also generate mind maps and flowcharts from high-level JSON, and manage tags, favorites, and bidirectional links:

lionote-cli mind set --id <noteId> --data "<mind map JSON>" --json
lionote-cli flow set --id <noteId> --data "<flowchart JSON>" --json
lionote-cli tag add --id <noteId> --name "project" --json
lionote-cli fav set --id <noteId> --json
lionote-cli link add --id <sourceNoteId> --target <targetNoteId> --json

Run lionote-cli --help to see all commands and options.

Rules for AI agents

  1. Run lionote-cli capabilities --json to discover capabilities, then run lionote-cli doctor --json.
  2. Create, append, or update notes only when writeSafe=true; treat desktopRunning as status information.
  3. Read an existing note with read <noteId> --json before changing it, to confirm the target and current content.
  4. Prefer update <noteId> --append when possible. State clearly when a full-body replacement will overwrite content.
  5. Use the stable lionote-cli command name. Do not guess installation or data-directory paths. If discovery fails, check the app account and storage settings first. The macOS App Store version follows the current app account and does not accept directory or database overrides.

The CLI performs the actual local operation. A Skill or agent prompt can help an AI discover and call it correctly, but cannot replace an installed and accessible CLI.

Contributors: Ray