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.
This is the version 3.x documentation. If you prefer to use an older version you can still read the version 2 README or version 1 README.
- 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 usepip3instead)pocketsnack --config- Add your Pocket API consumer key to the config file
pocketsnack --authorise- You are now ready to enjoy using pocketsnack from any directory
- 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.
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.
| setting | type | description |
|---|---|---|
| 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 tbr archive when using --lucky_dip |
| 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 --stash and remain in your Pocket List |
| ignore_faves | boolean | if set to true favorited items will be ignored by --stash and remain in your Pocket List |
| fave_dupes | boolean | if set to true the remaining (original) item will be favorited when duplicates are removed with --dedupe |
| replace_all_tags | boolean | if set to true all tags will be removed by --stash when adding the archive_tag, except anything in retain_tags |
| retain_tags | list | a list of tag names - these tags will not be removed by --purge, nor by --stash if replace_all_tags is set to true |
| 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 --lucky_dip. This is a subset of item_per_cycle, not in addition to the total. |
| num_images | integer | how many images (if there are images in your list) should be included in each --lucky_dip. This is a subset of item_per_cycle, not in addition to the total. |
| num_longreads | integer | how many long reads (if there are long reads in your list) should be included in each --lucky_dip. This is a subset of item_per_cycle, not in addition to the total. The definition of a long read is determined by longreads_wordcount |
| pocket_access_token | string | access token required to interact with the Pocket API. This will be updated when you run --authorise and should not be edited manually. |
Save and close when you're done. You can edit this file again at any time by running pocketsnack --config.
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 'aa11bb-zz9900xx'
To run commands, use pocketsnack [command].
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 pocketsnack.
Prints the current version number to screen.
Create or edit your config file which is stored at ~/.pocketsnack_conf.yml.
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 items_per_cycle in settings.yaml. Note that if num_videos and num_images add up to more than items_per_cycle, then --lucky_dip will only return the total specified in items_per_cycle. Videos take precedence.
Get information on items in a list (if LOCATION is -l) or TBR items in your archive (if LOCATION is -a).
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: --list, --tbr, --archive, or --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 ignore_faves and ignore_tags in 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.
Used with --purge, it purges tags on items in the archive.
Used with --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 tbr archive.
Used with --purge, it purges tags only on items in the tbr archive.
For use with --purge - purge tags from your entire Pocket account.
Used with --dedupe, it de-duplicates your entire Pocket account.
Restrict the current action command to only items updated more recently than SINCE number of days.
Restrict the current action command to only items updated less recently than BEFORE number of days.
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 add or 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:
pocketsnack --lucky_dip
Run lucky_dip but only choose from items last updated longer ago than one week:
pocketsnack -d -o 7
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.
Run pip uninstall pocketsnack or pip3 uninstall pocketsnack.
-
Delete the executable link, e.g.
rm /usr/local/bin/pocketsnackIf 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
Please log an issue - but check the existing issues first in case it's already been/being dealt with.