Lionote CLI Guide
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
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
| Platform | First-time setup | While the app is running | While the app is closed |
|---|---|---|---|
| macOS | Enable the CLI in Settings and register the terminal command | The app handles CLI commands | The app must start before commands can run; the launcher attempts to start it and wait until it is ready |
| Windows | Install the desktop app and reopen your terminal or agent | Automatically connects to the app to execute commands and refresh notes | Reads and writes local notes independently without starting the app |
| Linux | Install a desktop package containing the CLI and configure the command and PATH | Runs independently and notifies the app to refresh after writes | Reads 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 --jsonCall 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
- Open Lionote and enable “Command line interface” in Settings.
- 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.
- Reopen your terminal or AI tool and run
lionote-cli doctor --jsonto 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 --jsonNo 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 --jsonTo 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/binis 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 --jsonOn 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 --jsonSpecifying 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 --jsondoctor 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.
List, read, and search
lionote-cli list --json
lionote-cli read <noteId> --json
lionote-cli search --query "meeting" --limit 20 --jsonsearch 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" --jsonFor longer content, read from a file or standard input:
lionote-cli create --title "Imported content" --file "./note.md" --jsonUpdate 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" --jsonupdate 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 -.
Note links and backlinks
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> --jsonBy 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:
| Field | Meaning |
|---|---|
outgoing | Notes referenced by the current note |
incoming | Notes referencing the current note; mutual references appear in both groups |
locations | Reference locations: area=body/mind/flow, with nodeId for diagram nodes |
relationIds | The 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> --jsonmindMap.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> --jsonRun lionote-cli --help to see all commands and options.
Rules for AI agents
- Run
lionote-cli capabilities --jsonto discover capabilities, then runlionote-cli doctor --json. - Create, append, or update notes only when
writeSafe=true; treatdesktopRunningas status information. - Read an existing note with
read <noteId> --jsonbefore changing it, to confirm the target and current content. - Prefer
update <noteId> --appendwhen possible. State clearly when a full-body replacement will overwrite content. - Use the stable
lionote-clicommand 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.
