KonMari your Pocket tsundoku from the command line
pocketsnack is a command line application offering various commands to make your Pocket account more manageable. You can de-duplicate your list, purge unwanted tags, and hide your enormous 'to be read' list in a special archive so that looking at it doesn't become paralysing. Tested on MacOS, Ubuntu Linux and Windows 10. Expected to run on other platforms.
- Python 3.6.1 or higher
xdg-utils(on Linux & BSD)
- A web browser to obtain a Pocket token
- make sure you have installed Python version 3.6.1 or higher.
pip install pocketsnack(you may need to use
- Add your Pocket API consumer key to the config file
- You are now ready to enjoy using pocketsnack from any directory
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) or Mac.
- Your new app will show a consumer key, which you need to paste into the first line in your configuration file.
Creating a configuration file
Before you can use
pocketsnack you need to create a configuration file. If you run any command (including simply
pocketsnack without an argument) when your configuration file doesn't exist, a new file will be created and will open in your default application for editing
yaml files. You must copy in the consumer key referred to above, and may adjust any other settings.
You can adjust most settings, but the defaults should be sensible for most users if you just want to get started.
|pocket_consumer_key||string||the consumer key provided by Pocket when you register your 'app' (see below)|
|items_per_cycle||integer||how many items you want to bring in to the List from your
|archive_tag||string||the tag to use to identify items in your 'to be read' archive|
|ignore_tags||list||a list of tag names - items with any of these tags will be ignored by
|ignore_faves||boolean||if set to
|fave_dupes||boolean||if set to
|replace_all_tags||boolean||if set to
|retain_tags||list||a list of tag names - these tags will not be removed by
|longreads_wordcount||integer||determines how long a 'longread' is.|
|num_videos||integer||how many videos (if there are videos in your list) should be included in each
|num_images||integer||how many images (if there are images in your list) should be included in each
|num_longreads||integer||how many long reads (if there are long reads in your list) should be included in each
|pocket_access_token||string||access token required to interact with the Pocket API. This will be updated when you run
Save and close when you're done. You can edit this file again at any time by running
Authorising your app with a Pocket access token
Pocket uses OAuth to confirm that your app has permission from your user account to do things 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 the config file, run
pocketsnack --authorise to get your token.
You should now have a line a value for
pocket_access_token: that looks something like
To run commands, use
Outputs help for each command
Outputs the full JSON from 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 your config file. You also need to run
--authorise if you want to change the Pocket account you are using with
Prints the current version number to screen.
Create or edit your config file which is stored at
Removes duplicates from your List, TBR archive, full Archive, or everything, depending on the flag you use with it. This is an extension of the functionality provided by pickpocket.
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.yaml. Note that if
num_images add up to more than
--lucky_dip will only return the total specified in
items_per_cycle. Videos take precedence.
-i, --info LOCATION
Get information on items in a list (if LOCATION is
-l) or TBR items in your archive (if LOCATION is
You can use
--purge to clear all tags in your List, TBR achive, full Archive, or everything - 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.
Adds the archive tag to everything in your list, and then archives them. Depending on the value of
settings.yaml, 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 your config.
--purge, it purges tags on items in the archive.
--dedupe, it restricts de-duplication to the full Pocket Archive.
Same as archive but for your Pocket List instead of your archive.
Used in conjuction with
--dedupe to dedupe only items in the
--purge, it purges tags only on items in the
For use with
--purge - purge tags from your entire Pocket account.
--dedupe, it de-duplicates your entire Pocket account.
-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 a change 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).
Find out how many
TBR items are in the archive:
pocketsnack --info -a
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
A note on version 3
Version 3.x introduces a new YAML format for the settings file. This approach also allows for changes to the settings file without having to re-install
pocketsnack, which was an unintended side effect of the previous approach.
Uninstalling or moving v1 script to a new directory
If you installed with pip
pip uninstall pocketsnack or
pip3 uninstall pocketsnack.
If you installed using the legacy version 1 install.sh script
Delete the executable link, e.g.
If you don't do this when re-installing in a different directory, running
pocketsnackwill fail because it will still be pointing at the old directory.
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.