@cardinalapps/cli v1.3.3

Cardinal Server CLI

The Cardinal Server CLI app is the command line version of Cardinal Server. It runs on Linux, macOS, and Windows, and in Node.js and Docker.

This app comes with a handy-dandy Wizard 🧙.

Usage

Install with npm on Linux, macOS, or Windows

You can use npm to install the app. If you don't have npm, you can get it by installing Node.js first (requires version 14+). Afterwards, run:

npm i -g @cardinalapps/cardinal-server-cli

When installed with npm on Linux, macOS, or Windows, you can run commands using the global installation like so:

cardinal-server media --help
cardinal-server database list
cardinal-server media source add -d /some/dir

Install With Docker/Podman

Cardinal Server can run in a container, and there is an official image available on Docker Hub.

The app will behave a little differently when running inside of a container. For example, it will automatically start the web server when the container is launched, and you won't need to supply certain options when using certain commands.

You'll need to start by creating a volume, which will contain your database, image cache, and logs:

docker volume create cardinal-server-vol

With the volume created, you can start the container using the run command with the following options to expose the correct ports, mount the volume, and bind your media source(s).

docker run -t --net=host -v cardinal-server-vol:/usr/src/app/mount -v <MEDIA_SOURCE>:/usr/src/app/media/<TYPE>/<NAME>:Z somebeaver/cardinal-server

You'll need to replace a few things in this command:

• <MEDIA_SOURCE> with the path to your media files (you can add more than one source, using more -v options)
• <TYPE> with the media type (music, photos, cinema, books)
• <NAME> with a unique name for this source

You must always supply the same options when starting the Cardinal Server container. If options change, you'll need to reindex.

If you're using Docker through an interface (e.g., Synology Docker app), you must start the container with "host" networking, and you must correctly mount the volumes to the directories seen in the command above.

Once the container is running, you can execute commands similarily to the non-containerized version of the app, but with just a bit more boilerplate. For example, these are the same commands as the non-container example above.

docker exec -t -i <CONTAINER_ID> npm run app -- media --help
docker exec -t -i <CONTAINER_ID> npm run app -- database list
docker exec -t -i <CONTAINER_ID> npm run app -- media source add -d /some/dir

You must always supply the -t and -i options when executing commands, and you'll need to replace <CONTAINER_ID> with the ID of the container we just started. Run docker ps to get the ID.

When running in a container, some aspects of the app will be handled automatically, so some commands will not be available.

The Wizard

Whether you're using the CLI app in a container or not, the easiest way to get started is with the wizard. It'll help you run the right commands to get everything set up in your environment.

cardinal-server wizard

Commands

Use the app's help pages to see a full list of commands, and detailed information about each one.

• wizard - Helpful Assistant

• start* - Launch Cardinal Server

• database

  • create - Create a new database

  • list - Print all your databases

  • info - Get information about a database

  • delete - Delete database(s)

• media

  • source - Manage media sources (aka your media directories)

    • add - Add a media source

    • remove - Remove a media source

  • scan - Scan directories for supported media files

  • import - Index media from your sources

• webserver*

  • start* - Launch Cardinal Server

* Not available when running in a container (it's handled automatically).

Q&A

Q: Can I use the GUI from the Desktop app with the CLI app?

A: Unfortunately not. It's too tightly coupled with Electron's IPC methods to be used outside of Electron. It's going to get replaced with a much more powerful admin panel, but until then, the CLI app can do everything you need.

Troubleshooting

It says the address is already in use

Something else on the network is already using that port with that IP. Be sure that Cardinal Server isn't already running somewhere else on the network.

You can also use the --host and --port options with the webserver start command to manually set those values.

I don't see the wizard icon thingy

Your terminal doesn't support emojis. Sorry Command Prompt users.

I can't interact with the app in Docker

You ran the command without the -t and -i options.

Uninstall

To uninstall the CLI app, run:

npm uninstall -g cardinal-server-cli

Development

To develop for this app, clone the repo, install the dependencies using npm i, and run CLI commands with the following syntax:

// In the project root:

npm run app -- <cli-command>

// Example
npm run app -- media scan --dir /path/to/dir

License

Uses the GPLv3 software license.