sncli Agent Plugin

This repository packages the existing sncli Simplenote command-line client as a local agent plugin for Codex and Claude Code.

The plugin layer does not replace sncli, change the Simplenote protocol, or store credentials. It adds agent-facing metadata and workflow instructions so an installed agent can safely search, create, update, tag, and sync Simplenote notes through the normal sncli CLI.

What Is Included

.agents/plugins/marketplace.json          Codex local marketplace entry
.claude-plugin/marketplace.json           Claude Code local marketplace entry
plugins/sncli/.codex-plugin/plugin.json   Codex plugin manifest
plugins/sncli/.claude-plugin/plugin.json  Claude Code plugin manifest
plugins/sncli/skills/sncli/SKILL.md       Shared agent workflow instructions
plugins/sncli/commands/sncli.md           Claude Code /sncli command

The Python package and console UI are still available from the same checkout. Use the plugin when you want an agent to operate your Simplenote notes; use plain sncli when you want the classic terminal or scripting interface.

Quick Start

Clone this repository and install the CLI runtime:

git clone https://github.com/risingdream/sncli.git
cd sncli
python3 -m pip install -e .
sncli --help

Configure Simplenote credentials in ~/.snclirc, or provide SN_USERNAME and SN_PASSWORD in the environment:

[sncli]
cfg_sn_username = user@example.com
cfg_sn_password = app-password-or-account-password

Install the Codex plugin from the repository root:

codex plugin marketplace add .
codex plugin add sncli@personal

Install the Claude Code plugin from the repository root:

claude plugin marketplace add . --scope user
claude plugin install sncli@sncli-local --scope user

Start a new Codex or Claude Code session after installation so plugin skills and commands are refreshed.

Windows Notes

sncli is distributed as a Python command-line package. On Windows, Python creates a sncli.exe console-script shim during installation; the agent plugin does not need a separate native executable.

From PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
sncli --help
where.exe sncli

The default Windows paths are:

%USERPROFILE%\.snclirc
%USERPROFILE%\.sncli

The plugin marketplace commands are the same from the repository root.

Agent-Safe Usage

Agents should use explicit subcommands instead of launching bare sncli, which starts the interactive terminal UI.

Search cached notes:

sncli -n list "query"

View a note after confirming its key from list output:

sncli -k <key> dump

Create a note non-interactively:

printf '%s\n' "# Title" "" "Body text" | sncli create -
sncli sync
sncli -n list "Title"
sncli -k <key-from-list> tag add project notes
sncli sync

Update an existing note non-interactively:

sncli -n list "query"
sncli -n -k <key> export | jq -r '.content' > /tmp/sncli-edit.md
# update /tmp/sncli-edit.md
EDITOR="cp /tmp/sncli-edit.md" sncli -k <key> edit
sncli -k <key> tag add project notes
sncli sync

Always confirm note keys from sncli list output. After create, edit, trash, untrash, pin, markdown, or tag operations, run sncli sync before relying on a follow-up read.

Classic CLI

The original sncli command-line and console GUI behavior is preserved. For the released CLI package only, install with pip3 install sncli.

sncli [OPTIONS] [COMMAND] [COMMAND_ARGS]

Common commands:

sync                        perform a full sync with the server
list [search_string]        list notes
export [search_string]      export notes as JSON
dump [search_string]        dump note contents
create [-]                  create a note, optionally from stdin
import [-]                  import raw JSON note data
edit [+line_number]         edit a note by key
trash | untrash             trash or restore a note
pin | unpin                 pin or unpin a note
markdown | unmarkdown       toggle markdown system tag
tag get|set|add|rm          manage note tags

Run sncli --help for the full command list. The classic terminal UI starts when sncli is run without a subcommand.

Documentation

• docs/plugins.rst explains plugin installation, authentication, cache, sync, Windows behavior, and validation in more detail.
• docs/install.rst covers the Python package installation flow.
• docs/cl-usage.rst covers command-line usage.
• docs/gui-usage.rst covers the terminal UI.
• docs/configuration.rst covers .snclirc options.
• docs/tips.rst contains additional usage patterns.

Validation

Validate plugin metadata and the CLI entry point from the repository root:

python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/sncli
claude plugin validate plugins/sncli
sncli --help

The Codex validator imports PyYAML. If the active Python environment does not provide it, run the validator from a temporary virtual environment that has PyYAML installed.

Limitations

• The plugin is an agent packaging layer; it does not include an MCP server.
• Simplenote network sync still requires valid credentials and network access.
• Bare sncli starts the terminal GUI. Agent workflows should use explicit subcommands unless the user asks for the GUI.
• Native Windows terminal UI support remains limited by the underlying console stack, but command-line workflows and plugin installation work through the Python console-script shim.

Contributing

Pull requests are welcome. Keep plugin changes focused on agent packaging, metadata, documentation, and safe CLI workflows unless you are intentionally changing the underlying Python client.

For release builds, bump the version in setup.py, install requirements-release.txt, run python -m build, and upload with twine.

Credits

This application pulls in and uses simplenote.py by mrtazz and notes_db.py from nvpy by cpbotha.