lnk

Introduction

lnk is URL-shortening client that currently supports three services: bit.ly, goo.gl and tinyurl. Essentially, lnk is a collection of separate command-line utilities for each of these services, however the interfaces to them are largely the same so that you can easily switch between them. Note, however, that not all services provide the same information or have the same functionality. For example, for bit.ly, you can not only manipulate short and long links, but also access metrics about links and also information about your user-profile. At the same time, goo.gl provides similar functionality as bit.ly, however it has no concept of a ‘user-profile’, so you cannot retrieve information about yourself. tinyurl is the retarded child among the three, it can only shorten links. In the sub-sections below you can find full lists of all functionality provided by each of the three currently-supported services.

Usage

Services

The lnk command-line utility is structured into a set of sub-commands for each of its services, as well as one for configuration of settings. You can see a list of available sub-commands simply by typing $ lnk, which is equivalent to $ lnk --help:

Note

This is true for all commands of lnk: typing the command alone does not execute anything, but is interpreted as a call for help and is equivalent to passing the –help flag.

$ lnk
Usage: main.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  bitly    bit.ly command-line client.
  tinyurl  tinyurl command-line client.
  config   Configuration interface.
  googl    goo.gl command-line client.

However you need not specify the service you wish to use every time you use lnk, as its configuration-system allows for default-settings (refer to the config section for more information). One such default-setting is your default service, which lnk will always use if you omit the service sub-command. If your current default-service is bit.ly, $ lnk ... is equivalent to typing $ lnk bitly ....

Note

You can type “bit.ly” or “bitly”, “goo.gl” or “googl” to specify the respective command.

Commands

Each such sub-command (for each URL-shortening service + config) is further structured into a set of commands which perform some specific task, such as shortening lnks or retrieving statistics for a link. This is where the services differ, as they do not all provide the same set of commands. bit.ly is the most complete and you can see what commands it supplies by typing $ lnk bitly or $ lnk bitly --help:

$ lnk bitly --help
Usage: lnk bitly [OPTIONS] [ARGS]... COMMAND [ARGS]...

  bit.ly command-line client.

Options:
  -v, --verbose  Controls the level of verbosity (in case of exceptions).
  --version      Show the version and exit.
  --help         Show this message and exit.

Commands:
  history  Retrieve link history.
  info     Information about links.
  key      Generate an API key for user metrics and...
  link     Link shortening and expansion.
  stats    Statistics and metrics for links.
  user     Show meta-information for the current user.

Options & Arguments

Each command takes, of course, further options and arguments, which you can see by typing $ lnk <service> <command>. For example, here’s the usage information for bitly’s link command:

$ lnk bitly link --help
Usage: main.py [OPTIONS] [URLS]...

  Link shortening and expansion.

Options:
  -c, --copy / -n, --no-copy  Whether or not to copy the first link to the
                              clipboard.
  -q, --quiet / -l, --loud    Whether or not to print warnings.
  -e, --expand URL            Expand a short url (bitlink).
  -s, --shorten URL           Shorten a long url.
  --pretty / --plain          Whether to show the links in a pretty box or as a plain list.
  --help                      Show this message and exit.

Verbosity

lnk has a special verbosity system that controls how much information you see when an exception is thrown. There are four levels of verbosity, where the first level will always show the error message and the third level the (Python) type. What the other levels show depends on the context of the exception, so you will have to just increment the level to see if more information is available.

There are two ways to manipulate the level of verbosity:

  1. Passing the -v multiple times. The default level already is 1, so passing -v increments the verbosity level to 2.
  2. Passing the -l or --level flag, which takes as its argument the level of verbosity you wish to specify. Level 0 means the default level will be taken, which you can configure in the default settings of lnk.

Note

The verbosity must be passed passed to the sub-commands for each service + config, i.e. $ lnk bitly -vv link ... is valid, while lnk -vv bitly link or $ lnk bitly link -vv are ill-formed commands.

bit.ly

The bit.ly (or “bitly”) command interfaces with the bit.ly API and provides the following functionality:

Usage: lnk bitly [OPTIONS] [ARGS]... COMMAND [ARGS]...

  bit.ly command-line client.

Options:
  -v, --verbose        Increments the level of verbosity.
  -l, --level INTEGER  Controls the level of verbosity.
  --version            Show the version and exit.
  --help               Show this message and exit.

Commands:
  history  Retrieve link history.
  info     Information about links.
  key      Authorization management.
  link     Link shortening and expansion.
  stats    Statistics and metrics for links.
  user     Show meta-information for the current user.

Authorization

The bitly command requires authorization to access user-sensitive data such as link history. For this, the key command exists, which you must call once before being able to perform any actions with the bit.ly service. There are two ways to use this command, as you can see in its usage:

Usage: lnk [OPTIONS]

  Authorization management.

Options:
  -g, --generate           Generate a new api key (asks for login/password).
  -l, --login TEXT         Generate a new api key with this login.
  -p, --password TEXT      Generate a new api key with this password.
  -s, --show / -h, --hide  Whether to show or hide the generated API key.
  -w, --who                Show who is currently logged in.
  --help                   Show this message and exit.

The first, easiest and safest way is to execute $ lnk bitly key --generate, which will prompt you for your login and password. The second way is to pass those two items in the command directly, like so: $ lnk bitly key --login <your_bitly_login> --password <your_bitly_password>. The first way is safer because the password prompt hides the input, so if a hacker is looking over your shoulder he or she will not see your password and find out what naughty links you’ve been shortening.

goo.gl

The goo.gl command interfaces with the goo.gl API and provides almost just as much functionality as the bit.ly command, with the exception of the user command, which does not exist for goo.gl (the API provides no information about the account connected to given credentials). Here is the usage for the goo.gl command:

Usage: lnk googl [OPTIONS] [ARGS]... COMMAND [ARGS]...

  goo.gl command-line client.

Options:
  -v, --verbose        Increments the level of verbosity.
  -l, --level INTEGER  Controls the level of verbosity.
  --version            Show the version and exit.
  --help               Show this message and exit.

Commands:
  history  Retrieve link history.
  info     Information about links.
  key      Authorization management.
  link     Link shortening and expansion.
  stats    Statistics and metrics for links.

Authorization

The authorization-procedure for goo.gl is rather special, as it doesn’t all happen on the command-line. When you execute $ lnk googl key --generate, which you must do before anything else when first using lnk with goo.gl, your default web-browser is opened on a page asking you to authorize lnk to access your information. When you accept, you are shown an access-token which you then have to paste into lnk, which expects this token and shows an appropriate prompt for it.

tinyurl

The tinyurl command allows you to shorten links with tinyurl. The service itself is quite simple and provides only this functionality, so that is also the only thing you can do when you execute this command, as can be seen from its usage string:

Usage: lnk tinyurl [OPTIONS] [ARGS]... COMMAND [ARGS]...

  tinyurl command-line client.

Options:
  -v, --verbose        Increments the level of verbosity.
  -l, --level INTEGER  Controls the level of verbosity.
  --version            Show the version and exit.
  --help               Show this message and exit.

Commands:
  link  Link shortening.

Authorization

The tinyurl command requires no authorization.

config

lnk includes a configuration-management-system that allows you to keep and modify default settings for the application itself, for the services and for all of their commands. This configuration-management-system can be accessed via the config command, whose usage looks as follows:

Usage: lnk config [OPTIONS] [WHICH] [COMMAND]

  Configuration interface.

Options:
  -k, --key KEY             A key to show or manipulate.
  -v, --value VALUE         A new value for a key.
  -q, --quiet / -l, --loud  Whether to visualize changes.
  -a, --all, --all-keys     Whether to show all keys.
  --help                    Show this message and exit.

You can access settings of the bitly, googl or tinyurl services as well as for lnk itself (such as the default service) and also the config command by typing lnk config <which>. For the services (bitly, googl and tinyurl), you can also specify a command for which to configure settings, e.g. lnk config googl link would give you access to the settings for the googl/goo.gl’s link command. If you provide no value for which, it is assumed you wish to modify the configuration of lnk. In general, any setting is characterized by a key and a value, e.g. the key for lnk’s default service would be “service” and the value for example “tinyurl”.

To display settings, you can then either pass the -a/--all/--all-keys flag, which will show you all available keys, or specify them by their name using the -k, --key option. This will only show you the keys. To change the value of a key, you have to supply a new value with the -v, --value option. The keys and values are mapped to each other in order of their appearance, i.e. for a command such as lnk config bitly -k <a> -v 1 -k <b> -v 2 `, the first key '<a>' (not a real key, just for proof of concept)  will be given the first value 1 and the second key '<b>' is given the value 2. This mapping-system means the above command is equivalent to this command: :code:`lnk config bitly -k <a> -k <b> 1 2. Any remaining keys without a value are only displayed.

Note

You cannot add settings. If the argument to -k is not found in the settings you wish to modify, an exception is raised.

Example

Here is how you would change the default service using this configuration system. First, see which keys are available for lnk and what their values are:

$ lnk config lnk --all
verbosity: 0
copy: True
service: googl

Which you can also do like this:

$ lnk config lnk -k verbosity -k copy -k service
verbosity: 0
copy: True
service: googl

Then, pass a new value for the “service” key:

$ lnk config lnk -k service -v bitly
service: googl => bitly

Now when you access link, stats or any other command without explicitly stating the service, this will be for bitly rather than googl. Had you not wanted to plague yourself with that output, you could have asked lnk to keep quiet about its changes with the -q/--quiet flag (whose default value you can also change in the config command’s settings):

$ lnk config lnk -q -k service -v bitly

Source Code

You can find documentation for lnk‘s source-code here.