Usage

Once installed, shaarli-client provides the shaarli command, which allows to interact with a Shaarli instance’s REST API.

Getting help

The -h and --help flags allow to display help for any command or sub-command:

$ shaarli -h

usage: shaarli [-h] [-c CONFIG] [-i INSTANCE] [-u URL] [-s SECRET]
               [-f {json,pprint,text}] [-o OUTFILE] [--insecure]
               {get-info,get-links,post-link,put-link,get-tags,get-tag,put-tag,delete-tag,delete-link}
               ...
positional arguments:
  {get-info,get-links,post-link,put-link,get-tags,get-tag,put-tag,delete-tag,delete-link}
                        REST API endpoint
    get-info            Get information about this instance
    get-links           Get a collection of links ordered by creation date
    post-link           Create a new link or note
    put-link            Update an existing link or note
    get-tags            Get all tags
    get-tag             Get a single tag
    put-tag             Rename an existing tag
    delete-tag          Delete a tag from every link where it is used
    delete-link         Delete a link

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Configuration file
  -i INSTANCE, --instance INSTANCE
                        Shaarli instance (configuration alias)
  -u URL, --url URL     Shaarli instance URL
  -s SECRET, --secret SECRET
                        API secret
  -f {json,pprint,text}, --format {json,pprint,text}
                        Output formatting
  -o OUTFILE, --outfile OUTFILE
                        File to save the program output to
  --insecure            Bypass API SSL/TLS certificate verification
$ shaarli get-links -h

usage: shaarli get-links [-h] [--limit LIMIT] [--offset OFFSET]
                         [--searchtags SEARCHTAGS [SEARCHTAGS ...]]
                         [--searchterm SEARCHTERM [SEARCHTERM ...]]
                         [--visibility {all,private,public}]

optional arguments:
  -h, --help            show this help message and exit
  --limit LIMIT         Number of links to retrieve or 'all'
  --offset OFFSET       Offset from which to start listing links
  --searchtags SEARCHTAGS [SEARCHTAGS ...]
                        List of tags
  --searchterm SEARCHTERM [SEARCHTERM ...]
                        Search terms across all links fields
  --visibility {all,private,public}
                        Filter links by visibility

Examples

General syntax

$ shaarli <global arguments> <endpoint> <endpoint arguments>

Note

The following examples assume a Configuration file is used

GET info

$ shaarli get-info
{
    "global_counter": 1502,
    "private_counter": 5,
    "settings": {
        "default_private_links": false,
        "enabled_plugins": [
            "markdown",
            "archiveorg"
        ],
        "header_link": "?",
        "timezone": "Europe/Paris",
        "title": "Yay!"
    }
}

POST link

$ shaarli post-link --url https://w3c.github.io/activitypub/
{
    "created": "2018-06-04T20:35:12+00:00",
    "description": "",
    "id": 3252,
    "private": false,
    "shorturl": "kMkHHQ",
    "tags": [],
    "title": "https://w3c.github.io/activitypub/",
    "updated": "",
    "url": "https://w3c.github.io/activitypub/"
}

GET tags

$ shaarli get-tags --limit 5
[
    {
        "name": "bananas",
        "occurrences": 312
    },
    {
        "name": "snakes",
        "occurrences": 247
    },
    {
        "name": "ladders",
        "occurrences": 240
    },
    {
        "name": "submarines",
        "occurrences": 48
    },
    {
        "name": "yellow",
        "occurrences": 27
    }
]

GET tag

$ shaarli get-tag bananas
{
    "name": "bananas",
    "occurrences": 312
}

PUT tag

$ shaarli put-tag w4c --name w3c
{
    "name": "w3c",
    "occurrences": 5
}

New lines/line breaks

If you need to include line breaks in your descriptions, use a literal newline \n and $’…’ around the description:

$ shaarli post-link --url https://example.com/ --description $'One\nword\nper\nline'.

NOT (minus) operator

It is required to pass all values to –searchtags as a quoted string:

$ shaarli get-links --searchtags "video -idontwantthistag"

The value passed to –searchtags must not start with a dash, a workaround is to start the string with a space:

$ shaarli get-links --searchtags " -idontwantthistag -northisone"