v1_README.md

version 1 README

Each time the refresh command runs, it moves everything in My List to Archive with a particular tag, then randomly selects X number of items with that tag to go back into My List so that instead of an overwhelming number of things to be read, you just have the number you can comfortably expect to read per cycle (day, week etc).

Getting started

tl;dr

1. install python 3 and the requests module
2. copy settings-example.py to settings.py
3. create Pocket app and paste consumer key into settings.py
4. run bash install.sh and follow the prompts

Dependencies

You will need Python 3.x installed and it must be called by python3, rather than python. These instructions, and the install script, assume you are using a Unix-like (Linux, BSD, MacOS) operating system. Microsoft Windows is not currently supported.

On MacOS the easiest thing to do is to install Python 3 using Homebrew: brew install python.

Then install the Python requests module using pip: pip3 install requests

Settings

You will need to copy settings-example.py to a new file called settings.py before you start. You can do this however you like, but from the command line you could use cp settings-example.py settings.py, and then edit it with a text editor like nano.

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

1. Log in to Pocket in a web browser
2. Go to https://getpocket.com/developer and click 'CREATE NEW APP'
3. Complete the form: you will need all permissions, and the platform should be 'Desktop (other)'
4. Your new app will show a 'consumer key', which you need to paste into the first line in settings.py

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 you app consumer key into settings.py, when you run the install.sh bash script, this will run authorise for you. If you are doing everything manually you should run pocketsnack authorise to get your token (see below).

You should now have a line at the bottom of settings.py saying something like pocket_access_token = 'aa11bb-zz9900xx'

Usage

For most users you simply need to run install.sh and then forget about it. The install script will ask a series of questions, authorise your app, and optionally set up a daily or weekly task to refresh your list. On MacOS this is done via launchd and on Linux via cron. If you want to use cron instead of launchd on Mac, just choose 'Linux' when asked - but I wouldn't recommend it (read on for why).

In both cases, pocketsnack refresh will run at the specified time. In the case of cron, this will only happen if the machine is up and logged on - e.g. a server. In the case of launchd, the script will be associated with your user account. If your machine is sleeping or your account logged out at the scheduled time, it will run immediately when you wake the machine up or log in. This allows you to set it for, e.g. 5am and be confident that when you open your Macbook at 7am the script will run and your Pocket account will refresh.

If you use launchd, log files for stdout and errors will be created wherever you saved pocketsnack.

To run commands manually, use pocketsnack [command].

commands

archive

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.

authorise

This has an 's', not a 'z'.

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.

list

Same as archive but for your list instead of your archive.

lucky_dip

Returns items from the archive to the list, and removes the archive tag. The number of items returned is determined by items_per_cycle in settings.py. Note that if num_videos and 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.

purge_tags

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_tags requires a second argument: list, archive, or all, depending on where you want to purge tags.

refresh

Runs stash followed by lucky_dip. This is the command that is run by launchd or cron if you set it up using install.sh.

stash

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.py some items may remain in the List.

Uninstalling

Don't like pocket-snack any more or want to re-install it in a new directory? No problem, you will just need to do a little maintenance:

1. If you set up refresh on a Mac you should unload the plist file:

   launchctl unload ~/Library/LaunchAgents/com.getpocket.pocketsnack.plist

2. Once unloaded, you can delete it:

   rm ~/Library/LaunchAgents/com.getpocket.pocketsnack.plist

3. 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.

   rm /usr/local/bin/pocketsnack

Now you can safely delete the pocket-snack directory.

Bugs and suggestions

Please log an issue - but check the existing issues first in case it's already been/being dealt with.