linkding-cli
is a CLI to interact with a linkding instance.
- Installation
- Python Versions
- Usage
- Contributing
pip install linkding-cli
linkding-cli
is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
$ linkding --help
Usage: linkding [OPTIONS] COMMAND [ARGS]...
Interact with a linkding instance.
Options:
-c, --config PATH A path to a config file. [env var: LINKDING_CONFIG]
-t, --token TOKEN A linkding API token. [env var: LINKDING_TOKEN]
-u, --url URL A URL to a linkding instance. [env var: LINKDING_URL]
-v, --verbose Increase verbosity of standard output.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
--help Show this message and exit.
Commands:
bookmarks Work with bookmarks.
tags Work with tags.
Configuration can be provided via a variety of sources:
- CLI Options
- Environment Variables
- Configuration File
$ linkding -u https://127.0.0.1:8000 -t abcde12345 ...
$ LINKDING_URL=https://127.0.0.1:8000 LINKDING_TOKEN=abcde12345 linkding ...
The configuration file can be formatted as either JSON:
{
"token": "abcde12345",
"url": "https://127.0.0.1:8000",
"verbose": false
}
...or YAML
---
token: "abcde12345"
url: "https://127.0.0.1:8000"
verbose: false
Then, the linkding file can be provided via either -c
or --config
.
$ linkding -c ~/.config/linkding.json ...
When parsing configuration options, linkding-cli
looks at the configuration sources in
the following order:
- Configuration File
- Environment Variables
- CLI Options
This allows you to mix and match sources – for instance, you might have "defaults" in the configuration file and override them via environment variables.
Usage: linkding bookmarks [OPTIONS] COMMAND [ARGS]...
Work with bookmarks.
Options:
--help Show this message and exit.
Commands:
all Get all bookmarks.
archive Archive a bookmark by its linkding ID.
create Create a bookmark.
delete Delete a bookmark by its linkding ID.
get Get a bookmark by its linkding ID.
unarchive Unarchive a bookmark by its linkding ID.
update Update a bookmark by its linkding ID.
Usage: linkding bookmarks all [OPTIONS]
Get all bookmarks.
Options:
-a, --archived Return archived bookmarks.
-l, --limit INTEGER The number of bookmarks to return.
-o, --offset INTEGER The index from which to return results.
-q, --query TEXT Return bookmarks containing a query string.
--help Show this message and exit.
# Get all bookmarks, but limit the results to 10:
$ linkding bookmarks all --limit 10
# Get all archived bookmarks that contain "software":
$ linkding bookmarks all --archived --query software
Usage: linkding bookmarks archive [OPTIONS] [BOOKMARK_ID]
Archive a bookmark by its linkding ID.
Arguments:
[BOOKMARK_ID] The ID of a bookmark to archive.
Options:
--help Show this message and exit.
# Archive bookmark 12:
$ linkding bookmarks archive 12
Usage: linkding bookmarks create [OPTIONS] URL
Create a bookmark.
Arguments:
URL The URL to bookmark. [required]
Options:
-a, --archived Whether the newly-created bookmark should be
immediately archived.
-d, --description DESCRIPTION The description to give the bookmark.
-n, --notes NOTES Any Markdown-formatted notes to add to the bookmark.
--shared Whether the newly-created bookmark should be
shareable with other linkding users
--tags TAG1,TAG2,... The tags to apply to the bookmark.
-t, --title TITLE The title to give the bookmark.
--unread Whether the newly-created bookmark should be
marked as unread.
--help Show this message and exit.
# Create a bookmark:
$ linkding bookmarks create https://example.com
# Create a bookmark and immeditely archive it:
$ linkding bookmarks create -a https://example.com
# Create a bookmark with title, description, and tags:
$ linkding bookmarks create https://example.com -t Example -d "A description" --tags tag1,tag2
Usage: linkding bookmarks delete [OPTIONS] [BOOKMARK_ID]
Delete a bookmark by its linkding ID.
Arguments:
[BOOKMARK_ID] The ID of a bookmark to delete.
Options:
--help Show this message and exit.
# Delete the bookmark with an ID of 12:
$ linkding bookmarks delete 12
Usage: linkding bookmarks get [OPTIONS] [BOOKMARK_ID]
Get a bookmark by its linkding ID.
Arguments:
[BOOKMARK_ID] The ID of a bookmark to retrieve.
Options:
--help Show this message and exit.
# Get bookmark 12:
$ linkding bookmarks get 12
Usage: linkding bookmarks unarchive [OPTIONS] [BOOKMARK_ID]
Unarchive a bookmark by its linkding ID.
Arguments:
[BOOKMARK_ID] The ID of a bookmark to unarchive.
Options:
--help Show this message and exit.
# Unarchive bookmark 12:
$ linkding bookmarks unarchive 12
Usage: linkding bookmarks update [OPTIONS] BOOKMARK_ID
Update a bookmark by its linkdingn ID.
Arguments:
BOOKMARK_ID The ID of a bookmark to update. [required]
Options:
-u, --url URL The URL to assign to the bookmark.
-d, --description DESCRIPTION The description to give the bookmark.
-n, --notes NOTES Any Markdown-formatted notes to add to the bookmark.
--shared Whether the -created bookmark should be
shareable with other linkding users
--tags TAG1,TAG2,... The tags to apply to the bookmark.
-t, --title TITLE The title to give the bookmark.
--unread Whether the bookmark should be marked as
unread.
--help Show this message and exit.
# Update a bookmark with a new url:
$ linkding bookmarks update 12 -u https://example.com
# Update a bookmark with title, description, and tags:
$ linkding bookmarks update 12 -t Example -d "A description" --tags tag1,tag2
Usage: linkding tags [OPTIONS] COMMAND [ARGS]...
Work with tags.
Options:
--help Show this message and exit.
Commands:
all Get all tags.
create Create a tag.
get Get a tag by its linkding ID.
Usage: linkding tags all [OPTIONS]
Get all tags.
Options:
-l, --limit INTEGER The number of tags to return.
-o, --offset INTEGER The index from which to return results.
--help Show this message and exit.
# Get all tags, but limit the results to 10:
$ linkding tags all --limit 10
Usage: linkding tags create [OPTIONS] TAG_NAME
Create a tag.
Arguments:
TAG_NAME The tag to create. [required]
Options:
--help Show this message and exit.
# Create a tag:
$ linkding tags create sample-tag
Usage: linkding tags get [OPTIONS] TAG_ID
Get a tag by its linkding ID.
Arguments:
TAG_ID The ID of a tag to retrieve. [required]
Options:
--help Show this message and exit.
# Get tag 12:
$ linkding tags get 12
linkding-cli
doesn't have built-in utilities for modifying JSON output in any way.
Instead, it's recommended to use a tool like jq
. This allows for multiple new
outcomes, like pretty-printing:
$ linkding bookmarks all | jq
{
"count": 123,
"next": "https://127.0.0.1:8000/api/bookmarks/?limit=100&offset=100",
"previous": null,
"results": [
{
"id": 1,
"url": "https://example.com",
"title": "Example title",
"description": "Example description",
"website_title": "Website title",
"website_description": "Website description",
"tag_names": [
"tag1",
"tag2"
],
"date_added": "2020-09-26T09:46:23.006313Z",
"date_modified": "2020-09-26T16:01:14.275335Z"
}
]
}
...and slicing/parsing data:
$ linkding bookmarks all | jq '.results[0].title'
"Example title"
Usage: linkding user [OPTIONS] COMMAND [ARGS]...
Work with user info.
Options:
--help Show this message and exit.
Commands:
profile Get user profile info.
Usage: linkding user profile [OPTIONS]
Get user profile info.
Options:
--help Show this message and exit.
$ linkding user profile
Thanks to all of our contributors so far!
- Check for open features/bugs or initiate a discussion on one.
- Fork the repository.
- (optional, but highly recommended) Create a virtual environment:
python3 -m venv .venv
- (optional, but highly recommended) Enter the virtual environment:
source ./.venv/bin/activate
- Install the dev environment:
script/setup
- Code your new feature or bug fix on a new branch.
- Write tests that cover your new functionality.
- Run tests and ensure 100% code coverage:
poetry run pytest --cov linkding_cli tests
- Update
README.md
with any new documentation. - Submit a pull request!