Skip to content

Commit

Permalink
docs: Update the CLI docs to reference the published NPM package
Browse files Browse the repository at this point in the history
  • Loading branch information
MohamedBassem committed Apr 24, 2024
1 parent ac2f78f commit 4804f98
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 7 deletions.
93 changes: 88 additions & 5 deletions docs/docs/09-command-line.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,109 @@
# Command Line Tool (CLI)

Hoarder comes with a simple CLI for those users who want to do more advanced manipulation. Currently, the CLI comes packaged as a docker container. You can run it with:
Hoarder comes with a simple CLI for those users who want to do more advanced manipulation.

## Features

- Manipulate bookmarks, lists and tags
- Mass import/export of bookmarks

## Installation (NPM)

```
npm install -g @hoarderapp/cli
```


## Installation (Docker)

```
docker run --rm ghcr.io/mohamedbassem/hoarder-cli:release --help
```

## Usage

```
hoarder
```

```
Usage: hoarder [options] [command]
A CLI interface to interact with the hoarder api
Options:
--api-key <key> the API key to interact with the API (env: HOARDER_API_KEY)
--server-addr <addr> the address of the server to connect to (env: HOARDER_SERVER_ADDR)
-V, --version output the version number
-h, --help display help for command
Commands:
bookmarks manipulating bookmarks
lists manipulating lists
tags manipulating tags
whoami returns info about the owner of this API key
help [command] display help for command
```

And some of the subcommands:

```
hoarder bookmarks
```

```
Usage: hoarder bookmarks [options] [command]
Manipulating bookmarks
Options:
-h, --help display help for command
Commands:
add [options] creates a new bookmark
get <id> fetch information about a bookmark
update [options] <id> updates bookmark
list [options] list all bookmarks
delete <id> delete a bookmark
help [command] display help for command
```

```
hoarder lists
```

```
Usage: hoarder lists [options] [command]
Manipulating lists
Options:
-h, --help display help for command
Commands:
list lists all lists
delete <id> deletes a list
add-bookmark [options] add a bookmark to list
remove-bookmark [options] remove a bookmark from list
help [command] display help for command
```

## Optaining an API Key

To use the CLI, you'll need to get an API key from your hoarder settings. You can validate that it's working by running:

```
docker run --rm ghcr.io/mohamedbassem/hoarder-cli:release --api-key <key> --server-addr <addr> whoami
hoarder --api-key <key> --server-addr <addr> whoami
```

For example:

```
docker run --rm ghcr.io/mohamedbassem/hoarder-cli:release --api-key mysupersecretkey --server-addr https://try.hoarder.app whoami
hoarder --api-key mysupersecretkey --server-addr https://try.hoarder.app whoami
{
id: 'j29gnbzxxd01q74j2lu88tnb',
name: 'Test User',
email: 'test@gmail.com'
}
```

Check the help for the other available commands, but the main usecase for the CLI is to enable mass manipulation of your bookmarks. E.g. mass importing of bookmarks, mass deletions, etc.
4 changes: 2 additions & 2 deletions docs/docs/10-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ Currently importing bookmarks requires some technical knowledge and might not be
Run the following command to import all the links from `all_links.txt`:

```
cat all_links.txt | xargs -I{} docker run --rm ghcr.io/mohamedbassem/hoarder-cli:release --api-key <key> --server-addr <addr> bookmarks add --link {}
cat all_links.txt | xargs -I{} hoarder --api-key <key> --server-addr <addr> bookmarks add --link {}
```

## Import from other platforms

If you can get your bookmarks in a text file with one link per line, you can use the following command to import them using the [hoarder cli](https://docs.hoarder.app/command-line):

```
cat all_links.txt | xargs -I{} docker run --rm ghcr.io/mohamedbassem/hoarder-cli:release --api-key <key> --server-addr <addr> bookmarks add --link {}
cat all_links.txt | xargs -I{} hoarder --api-key <key> --server-addr <addr> bookmarks add --link {}
```

0 comments on commit 4804f98

Please sign in to comment.