Skip to main content

A CLI to interact with a linkding instance

Project description

🔖 linkding-cli: A CLI to interact with a linkding instance

CI PyPI Version License Code Coverage Maintainability

linkding-cli is a CLI to interact with a linkding instance.

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:

  1. Configuration File
  2. Environment Variables
  3. 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!

  1. Check for open features/bugs or initiate a discussion on one.
  2. Fork the repository.
  3. (optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
  4. (optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
  5. Install the dev environment: script/setup
  6. Code your new feature or bug fix on a new branch.
  7. Write tests that cover your new functionality.
  8. Run tests and ensure 100% code coverage: poetry run pytest --cov linkding_cli tests
  9. Update README.md with any new documentation.
  10. Submit a pull request!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

linkding_cli-2024.9.0.tar.gz (14.0 kB view hashes)

Uploaded Source

Built Distribution

linkding_cli-2024.9.0-py3-none-any.whl (14.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page