{"id":13530798,"url":"https://github.com/insanum/sncli","last_synced_at":"2025-12-29T23:05:18.094Z","repository":{"id":46491699,"uuid":"21809114","full_name":"insanum/sncli","owner":"insanum","description":"Simplenote CLI","archived":false,"fork":false,"pushed_at":"2024-08-03T20:38:01.000Z","size":3863,"stargazers_count":404,"open_issues_count":38,"forks_count":37,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-27T03:29:42.762Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insanum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-14T05:58:57.000Z","updated_at":"2025-02-23T07:12:34.000Z","dependencies_parsed_at":"2024-01-03T04:14:07.067Z","dependency_job_id":"24786372-1a39-483c-88ed-4c30c250a465","html_url":"https://github.com/insanum/sncli","commit_stats":{"total_commits":275,"total_committers":20,"mean_commits":13.75,"dds":0.5381818181818182,"last_synced_commit":"eb6869eaa5138629b61c4db56157f12d621fc161"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insanum%2Fsncli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insanum%2Fsncli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insanum%2Fsncli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insanum%2Fsncli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insanum","download_url":"https://codeload.github.com/insanum/sncli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246700075,"owners_count":20819821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T07:00:55.430Z","updated_at":"2025-12-29T23:05:18.080Z","avatar_url":"https://github.com/insanum.png","language":"Python","funding_links":[],"categories":["Productivity","Python","\u003ca name=\"note-taking\"\u003e\u003c/a\u003eNote taking"],"sub_categories":["Note Taking and Lists"],"readme":"sncli\n=====\n\nSimplenote Command Line Interface\n[![Documentation Status](https://readthedocs.org/projects/sncli/badge/?version=latest)](https://sncli.readthedocs.io/en/latest/?badge=latest)\n\nsncli is a Python application that gives you access to your Simplenote account\nvia the command line. You can access your notes via a customizable console GUI\nthat implements vi-like keybinds or via a simple command line interface that\nyou can script.\n\nNotes can be viewed/created/edited in *both an* **online** *and* **offline**\n*mode*. All changes are saved to a local cache on disk and automatically\nsync'ed when sncli is brought online.\n\n**Pull requests are welcome!**\n\nCheck your OS distribution for installation packages.\n\n### Requirements\n\n* [Python 3](http://python.org)\n* [pip](https://pip.pypa.io/en/stable/)\n* A love for the command line!\n\n### Installation\n\n* Via pip (latest release):\n  - `pip3 install sncli`\n* Manually:\n  - Clone this repository to your hard disk: `git clone https://github.com/insanum/sncli.git`\n  - Pipenv:\n    - Install the requirements `pipenv install`\n    - Run with `pipenv run sncli`\n  - or more manual:\n    - `python setup.py install`\n  - or with Docker (see the wiki for [Docker usage tips](https://github.com/insanum/sncli/wiki/Tips-and-Tricks#docker-usage-tips))\n    - docker build . -t sncli\n    - docker run --rm -it -v /tmp:/tmp -v \"$HOME/.sncli/:/root/.sncli/\" -v \"$HOME/.snclirc:/root/.snclirc\" sncli\n\n\n### Features\n\n* Console GUI\n  - full two-way sync with Simplenote performed dynamically in the background\n  - all actions logged and easily reviewed\n  - list note titles (configurable format w/ title, date, flags, tags, keys, etc)\n  - sort notes by date, alpha by title, tags, pinned on top\n  - search for notes using a Google style search pattern or Regular Expression\n  - view note contents and meta data\n  - view and restore previous versions of notes\n  - pipe note contents to external command\n  - create and edit notes (using your editor)\n  - edit note tags\n  - trash/untrash notes\n  - pin/unpin notes\n  - flag notes as markdown or not\n  - vi-like keybinds (fully configurable)\n  - Colors! (fully configurable)\n* Command Line (scripting)\n  - force a full two-way sync with Simplenote\n  - all actions logged and easily reviewed\n  - list note titles and keys\n  - search for notes using a Google style search pattern or Regular Expression\n  - dump note contents\n  - create a new note (via stdin or editor)\n  - import a note with raw json data (stdin or editor)\n  - edit a note (via editor)\n  - trash/untrash a note\n  - pin/unpin a note\n  - flag note as markdown or not\n  - view and edit note tags\n\n### Screenshots\n\n![sncli](docs/screenshots/screenshot1.png)\n![sncli](docs/screenshots/screenshot2.png)\n![sncli](docs/screenshots/screenshot3.png)\n![sncli](docs/screenshots/screenshot4.png)\n\n### HowTo\n\n```\nUsage:\n sncli [OPTIONS] [COMMAND] [COMMAND_ARGS]\n\n OPTIONS:\n  -h, --help                  - usage help\n  -v, --verbose               - verbose output\n  -n, --nosync                - don't perform a server sync\n  -r, --regex                 - search string is a regular expression\n  -k \u003ckey\u003e, --key=\u003ckey\u003e       - note key\n  -t \u003ctitle\u003e, --title=\u003ctitle\u003e - title of note for create (cli mode)\n  -c \u003cfile\u003e, --config=\u003cfile\u003e  - config file to read from (defaults to ~/.snclirc)\n\n COMMANDS:\n  \u003cnone\u003e                      - console gui mode when no command specified\n  sync                        - perform a full sync with the server\n  list [search_string]        - list notes (refined with search string)\n  export [search_string]      - export notes in JSON (refined with search string)\n  dump [search_string]        - dump notes (refined with search string)\n  create [-]                  - create a note ('-' content from stdin)\n  import [-]                  - import a note in JSON format ('-' JSON from stdin)\n  export                      - export a note in JSON format (specified by \u003ckey\u003e)\n  dump                        - dump a note (specified by \u003ckey\u003e)\n  edit [+line_number]         - edit a note (specified by \u003ckey\u003e, optionally jump to line)\n  \u003c trash | untrash \u003e         - trash/untrash a note (specified by \u003ckey\u003e)\n  \u003c pin | unpin \u003e             - pin/unpin a note (specified by \u003ckey\u003e)\n  \u003c markdown | unmarkdown \u003e   - markdown/unmarkdown a note (specified by \u003ckey\u003e)\n  tag get                     - retrieve the tags from a note (specified by \u003ckey\u003e)\n  tag set \u003ctags\u003e              - set the tags for a note (specified by \u003ckey\u003e)\n  tag add \u003ctags\u003e              - add tags to a note (specified by \u003ckey\u003e)\n  tag rm \u003ctags\u003e               - remove tags from a note (specified by \u003ckey\u003e)\n```\n\n#### Configuration\n\nThe current Simplenote API does not support oauth authentication so your\nSimplenote account information must live in the configuration file or in\nthe `SN_USERNAME` and `SN_PASSWORD` environment variables.\nPlease be sure to protect any file containing these secrets.\n\nThe flow sncli uses for finding the config file is:\n\n1. Specified on the command line with `-c` or `--config`.\n2. If `SNCLIRC` environment variable is set, use that.\n3. Finally will pull from default location of `$HOME/.snclirc`.\n\nThe following example `.snclirc` will get you going (using your account information):\n\n```\n[sncli]\ncfg_sn_username = lebowski@thedude.com\ncfg_sn_password = nihilist\n```\nOr, if using environment variables, run `sncli` like this:\n``` shell\nSN_USERNAME=lebowski@thedude.com SN_PASSWORD=nihilist ./sncli\n```\n\nStart sncli with no arguments which starts the console GUI mode. sncli with\nstart sync'ing all your existing notes and you'll see log messages at the\nbottom of the console. You can view these log messages at any time by pressing\nthe `l` key.\n\nView the help by pressing `h`. Here you'll see all the keybinds and\nconfiguration items. The middle column shows the config name that can be used\nin your `.snclirc` to override the default setting.\n\nSee example configuration file below for more notes.\n\n```\n[sncli]\ncfg_sn_username = lebowski@thedude.com\ncfg_sn_password = nihilist\n\n# as an alternate to cfg_sn_password you could use the following config item\n# any shell command can be used; its stdout is used for the password\n# trailing newlines are stripped for ease of use\n# note: if both password config are given, cfg_sn_password will be used\ncfg_sn_password_eval = gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.sncli-pass.gpg\n\n# see http://urwid.org/manual/userinput.html for examples of more key combinations\nkb_edit_note = space\nkb_page_down = ctrl f\n\n# note that values must not be quoted\nclr_note_focus_bg = light blue\n\n# if this editor config value is not provided, the $EDITOR env var will be used instead\n# warning: if neither $EDITOR or cfg_editor is set, it will be impossible to edit notes\ncfg_editor = nvim\n\n# alternatively, {fname} and/or {line} are substituted with the filename and\n# current line number in sncli's pager.\n# If {fname} isn't supplied, the filename is simply appended.\n# examples:\ncfg_editor = nvim {fname} +{line}\ncfg_editor = nano +{line}\n\n# this is also supported for the pager:\ncfg_pager = less -c +{line} -N {fname}\n```\n\n#### Editing notes\n\nThe flow sncli uses for editing notes is:\n\n1. create temporary file\n2. load the note contents into it\n3. launch the editor with the file\n4. wait for the editor to exit\n5. load the file contents into the internal note\n\nAs a result, the note doesn't get updated in sncli until the editor is closed.\nBy default, the temporary file is created in the OS default tempdir (eg. `/tmp/`\non Linux). This can be changed with the `cfg_tempdir` option. This may be useful\nto create temporary files on a persistent file system to avoid data loss. For\nexample:\n\n```\ncfg_tempdir = /home/user/.sncli/tmp/\n```\n\nThis directory must exist.\n\nNote that currently sncli does not clean up the tempfiles. This is to avoid the\npossibility of unrecoverable data loss in the case where sncli crashes between\nediting a note and saving or syncing the note. If using the OS default tempdir,\nthese should be deleted upon reboot. If using a persistent tempdir, one should\nclean them up periodically to avoid too many files cluttering the system. For\nconvenience, all tempfiles are created with the name prefix\n`sncli-temp-\u003ctimestamp\u003e-`.\n\n\n#### Note Title Format\n\nThe format of each line in the note list is driven by the\n`cfg_format_note_title` config item. Various formatting tags are supported for\ndynamically building the title string. Each of these formatting tags supports\na width specifier (decimal) and a left justification (-) like that supported\nby printf:\n\n```\n  %F - flags (fixed 5 char width)\n       X - needs sync\n       T - trashed\n       * - pinned\n       S - published/shared\n       m - markdown\n  %T - tags\n  %D - date\n  %N - title\n```\n\nThe default note title format pushes the note tags to the far right of the\nterminal and left justifies the note title after the date and flags:\n\n```\ncfg_format_note_title = '[%D] %F %-N %T'\n```\n\nNote that the `%D` date format is further defined by the strftime format\nspecified in `cfg_format_strftime`.\n\n#### Colors\n\nsncli utilizes the Python [Uwrid](http://urwid.org) module to implement the\nconsole user interface.\n\nAt this time, sncli does not yet support 256-color terminals and is limited to\njust 16-colors. Color names that can be specified in the `.snclirc` file are\nlisted [here](http://urwid.org/manual/displayattributes.html#standard-foreground-colors).\n\n### Searching\n\nsncli supports two styles of search strings. First is a Google style search\nstring and second is a Regular Expression.\n\nA Google style search string is a group of tokens (separated by spaces) with\nan implied *AND* between each token. This style search is case insensitive. For\nexample:\n\n```\n/tag:tag1 tag:tag2 word1 \"word2 word3\" tag:tag3\n```\n\nRegular expression searching also supports the use of flags (currently only case-insensitive) by adding a final forward\nslash followed by the flags. The following example will do a case-insensitive search for `something`:\n\n```\n(regex) /something/i\n```\n\n### Creating from command line\n\n```\n# create a new note and open in editor\nsncli create\n\n# create a new note with contents of stdin\necho 'hi' | sncli create -\n```\n\n### Importing\n\nsncli can import notes from raw json data (via stdin or editor). For example:\n\n```\necho '{\"tags\":[\"testing\",\"new\"],\"content\":\"New note!\"}' | sncli import -\n```\n\nAllowed fields are `content`, `tags`, `systemTags`, `modificationDate`, `creationDate`, and `deleted`.\n\n### Exporting\n\nsncli can export notes as json data to stdout. Example:\n\n```\n# export a single note by id\nsncli -k somekeyid export\n\n# export all notes\nsncli export\n\n# export notes matching search string\nsncli [-r] export some search keywords or regex\n```\n\nNote that sncli still stores all the notes data in the directory specified by\n`cfg_db_path`, so for easy backups, it may be easier/quicker to simply backup\nthis entire directory.\n\n### Tags\n\nNote tags can be modified directly from the command line. Example:\n\n```\n# Retrieve note tags, as one comma-separated string (e.g. \"tag1,tag2\")\nsncli -k somekeyid tag get                  # Returns \"tag1,tag2\"\n\n# Add a tag to a note, if it doesn't already have it\nsncli -k somekeyid tag add \"tag3\"           # Now tagged as \"tag1,tag2,tag3\"\n\n# Remove a tag from a note\nsncli -k somekeyid tag rm \"tag2\"            # Now tagged as \"tag1,tag3\"\n\n# Overwrite all of the tags for a note\nsncli -k somekeyid tag set \"tag2,tag4\"      # Now tagged as \"tag2,tag4\"\n```\n\nNote that in SimpleNote, tags are case-insensitive, so \"TAG2\", \"tag2\", and \n\"tAg2\" are interpreted as the same and will all be converted to lowercase.\n\n\n### Tricks\n\nI personally store a lot of my notes in\n[Votl/VimOutliner](https://github.com/insanum/votl) format. Specific to Vim, I\nput a modeline at the end of these notes (note that Emacs also supports\nmodelines):\n\n```\n; vim:ft=votl\n```\n\nNow when I edit this note Vim will automatically load the votl plugin. Lots of\npossibilities here...\n\n_Note: more tips and tricks on the [GitHub wiki](https://github.com/insanum/sncli/wiki/Tips-and-Tricks)!_\n\n### Microsoft Windows support\n\nThere is **partial** Windows support:\n\n* WSL and Cygwin versions of Python work\n* Native Windows support is limited:\n    * batch/command line like sync and view work\n    * UI interaction does not work BUT can be made to partially work via a monkey patch to Urwid (see https://github.com/urwid/urwid/issues/447)\n    * See https://github.com/insanum/sncli/issues/119 for details\n\n### Building and releasing\n\nFirst, bump the version in setup.py.\nEnsure python-build and twine are installed on your system.\n\nRun:\n\n```\n# activate venv\npip install -r requirements-release.txt  # install build and twine packages\npython -m build  # build the source and built distributions, outputs to dist/\ntwine upload dist/*  # Upload to pypi.  This may prompt for your pypi token.\n```\n\n### Thanks\n\nThis application pulls in and uses the\n[simplenote.py](https://github.com/mrtazz/simplenote.py) module by\n[mrtazz](https://github.com/mrtazz) and the\n[notes_db.py](https://github.com/cpbotha/nvpy/blob/master/nvpy/notes_db.py)\nmodule from [nvpy](https://github.com/cpbotha/nvpy) by\n[cpbotha](https://github.com/cpbotha).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsanum%2Fsncli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsanum%2Fsncli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsanum%2Fsncli/lists"}