When your Pocket list is overwhelming, pocket-snack lets you see just what you can read today
This is the version 2 documentation. If you haven't yet upgraded you can still use the version 1 README.
A note on version 2
All commands have changed since version 1 - read the Usage section carefully. This was necessary in order to provide better functionality without making the code too confusing.
One of the changes is that the
refresh command from version 1 no longer exists. This is so that
--before can be used with both
lucky_dip. If you want replicate
refresh you simply need to run
--stash followed by
--lucky_dip. From the command line you could do:
pocketsnack -s && pocketsnack -d
The automation of
pocketsnack refresh has also been removed. This didn't really work very consistently, and was causing a lot of maintenance headaches. I'm looking at how to bring it back in a different way, but for now it's been removed.
Getting started (tl;dr)
- make sure you have installed Python version 3.x (preferably 3.7 or higher)
pocketsnackusing git or the download link in releases
- move into the top
pip3 install .or if pip points to Python3,
pip install .
- Add Pocket consumer key to
- You are now ready to enjoy using pocketsnack
Installing Python 3
You will need Python 3.x installed. On MacOS the easiest thing to do is to install Python 3 using Homebrew:
brew install python.
You will need to copy
settings/settings-example.py to a new file -
settings/settings.py before you start. You can do this however you like, but from the command line you could use:
cp settings/settings-example.py settings/settings.py,
and then edit it with a text editor like
nano or VS Code, but any text editor will do the job - you could even use TextEdit or Notepad.
You can adjust most settings, but the defaults in
settings-example.py should be ok for most users. Check the comments in
settings.example.py for an explanation of each setting.
Creating a Pocket consumer key for your app
- Log in to Pocket in a web browser
- Go to
https://getpocket.com/developerand click 'CREATE NEW APP'
- Complete the form: you will need all permissions, and the platform should be Desktop (other)
- Your new app will show a consumer key, which you need to paste into the first line in
Authorising your app with a Pocket access token
Pocket uses OAuth to confirm that your app has permission from your user account to do stuff in your account. This means you need to authorise the app before you can do anything else. Once you have copied your app consumer key into settings.py, run
pocketsnack --authorise to get your token.
You should now have a line at the bottom of settings.py saying something like
pocket_access_token = 'aa11bb-zz9900xx'
To run commands, use
Outputs help for each command
Outputs the first article returned by a call to the API. Normally you will never need to use this.
This command has an 's', not a 'z', and the short version is a 'u', not an 'a'.
You need this to authorise your app. Everything else works exclusively on the command line, but authorise needs to open a browser to complete the authorisation process, so you need to run this on a machine with a web browser. It will authorise your app with your user, wait for you to confirm that you have completed the authorisation (by typing 'done') and then add the token to
settings.py. You also need to run
--authorise if you want to change the Pocket account you are using with
Returns items with the archive tag from the archive to the list, and removes the archive tag. The number of items returned is determined by
settings.py. Note that if
num_images add up to more than
items_per_cycle, lucky_dip will only return the total specified in
items_per_cycle. Videos take precedence.
You can use purge_tags to clear all tags in your List, Archive, or both, excluding the
archive_tag and any
retain_tags. This is useful if you've been using the Aus GLAM Blogs Pocket tool or anything else that retains the original tags from articles.
--purge requires a second argument:
--all, depending on where you want to purge tags.
NOTE that by design,
--purge will process all items in your archive, not just items with the
archive_tag. This may lead to miss-matches between the number returned by
--info --archive and the number of items processed by
Adds the archive tag to everything in your list, and then archives them. Depending on the value of
settings.py, and any before/since values, some items may be excluded and remain in the List.
Used in combination with
--info, this tells you how many items are in your archive and how many of them are 'long reads'. You can set the wordcount defining a long read in
settings.py. Used with
--purge, it purges tags on items in the archive.
Same as archive but for your list instead of your archive.
For use with
--purge - purge tags from both the List and the Archive.
-n, --since SINCE
Restrict the current action command to only items updated more recently than SINCE number of days.
-o, --before BEFORE
Restrict the current action command to only items updated less recently than BEFORE number of days.
What does 'updated' mean?
The Pocket API does not store a value for the date an items was first added. The only value we can get is since, which is a timestamp updated every time there is an update made to an item via or equivalent to any
modify API action. This could be when it is added to the List, move to the archive, moved out of the archive back into the List, or has changes made to tags (even if that tag update results in no actual change - i.e. if
--purge has been run against the item, regardless of whether it had any tags to begin with).
Stash only items updated in the last 2 days:
pocketsnack --stash -n 2
Stash only items NOT updated in the last 7 days:
pocketsnack --stash -o 7
Purge tags on all items in the List that were updated in the last day:
pocketsnack -pln 1
Run lucky_dip but only choose from items last updated longer ago than one week:
pocketsnack -d -o 7
Uninstalling or moving to a new directory
If you installed with pip
pip uninstall pocketsnack or
pip3 uninstall pocketsnack.
If you installed using the legacy install.sh script
- Delete the executable link:
If you don't do this when re-installing in a different directory, running
pocketsnack will fail because it will still be pointing at the old directory.
2. Now you can safely delete the pocket-snack directory:
rm -r pocketsnack
Bugs and suggestions
Please log an issue - but check the existing issues first in case it's already been/being dealt with.