A CLI to interact with a linkding instance
Project description
🔖 linkding-cli: A CLI to interact with a linkding instance
linkding-cli
is a CLI to interact with a linkding instance.
- Installation
- Python Versions
- Usage
- Contributing
Installation
pip install linkding-cli
Python Versions
linkding-cli
is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
Usage
Main Help
$ 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
Configuration can be provided via a variety of sources:
- CLI Options
- Environment Variables
- Configuration File
Example: CLI Options
$ linkding -u http://127.0.0.1:8000 -t abcde12345 ...
Example: Environment Variables
$ LINKDING_URL=http://127.0.0.1:8000 LINKDING_TOKEN=abcde12345 linkding ...
Example: Configuration File
The configuration file can be formatted as either JSON:
{
"token": "abcde12345",
"url": "http://127.0.0.1:8000",
"verbose": false
}
...or YAML
---
token: "abcde12345"
url: "http://127.0.0.1:8000"
verbose: false
Then, the linkding file can be provided via either -c
or --config
.
$ linkding -c ~/.config/linkding.json ...
Merging Configuration Options
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.
Bookmarks
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.
The bookmarks all
command
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.
Examples:
# 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
The bookmarks archive
command
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.
Examples:
# Archive bookmark 12:
$ linkding bookmarks archive 12
The bookmarks create
command
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.
Examples:
# 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
The bookmarks delete
command
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.
Examples:
# Delete the bookmark with an ID of 12:
$ linkding bookmarks delete 12
The bookmarks get
command
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.
Examples:
# Get bookmark 12:
$ linkding bookmarks get 12
The bookmarks unarchive
command
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.
Examples:
# Unarchive bookmark 12:
$ linkding bookmarks unarchive 12
The bookmarks update
command
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.
Examples:
# 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
Tags
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.
The tags all
command
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.
Examples:
# Get all tags, but limit the results to 10:
$ linkding tags all --limit 10
The tags create
command
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.
Examples:
# Create a tag:
$ linkding tags create sample-tag
The tags get
command
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.
Examples:
# Get tag 12:
$ linkding tags get 12
Misc.
Parsing and Pretty Printing Data
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": "http://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"
User Info
Usage: linkding user [OPTIONS] COMMAND [ARGS]...
Work with user info.
Options:
--help Show this message and exit.
Commands:
profile Get user profile info.
The user profile
command
Usage: linkding user profile [OPTIONS]
Get user profile info.
Options:
--help Show this message and exit.
Examples:
$ linkding user profile
Contributing
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!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file linkding_cli-2024.9.0.tar.gz
.
File metadata
- Download URL: linkding_cli-2024.9.0.tar.gz
- Upload date:
- Size: 14.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.5 Linux/6.5.0-1025-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a2181f34e6d6092e96510dc3cd5ee7d55bd1f1872aa90b15c76cd6927186f51e |
|
MD5 | 04c731580163614df9588a12ad544b1e |
|
BLAKE2b-256 | 2ab9b47190ee30a6b0a32c6085f86124a775bad906a60d2d79bb9b0f96dc2e6c |
File details
Details for the file linkding_cli-2024.9.0-py3-none-any.whl
.
File metadata
- Download URL: linkding_cli-2024.9.0-py3-none-any.whl
- Upload date:
- Size: 14.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.5 Linux/6.5.0-1025-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | be7819949111573bbda8d08d7e2fad0196b961d7b25610a4ff9befa81be927ce |
|
MD5 | 5383707e19ffe7d4e62522a548c01b38 |
|
BLAKE2b-256 | 9a90ae1ece2f5bbdd50e2c72fe424358977662c8702f61a2a5c27315b7cef21c |