Add page with CLI & JSON/RPC examples

[michaelherger]

We have a pretty complete CLI documentation built in to LMS. But it doesn't cover the use of those commands using tools like netcat, curl, or wget.

And maybe we could even render a more user friendly version of the above by converting it to markdown?...

[terual]

Good idea! If we also make a markdown version, how do we maintain both versions and keep them in sync?

[terual]

BTW, under the jsonrpc.js section in the docs there is an curl example, so it is really not too bad!

[terual]

Or is your idea to rewrite every example in the CLI documentation to curl instead of telnet?

[michaelherger]

I tried to use html2md with the document. But the outcome isn't great: all the navigation is missing, the code blocks are turned into quotes (due the poor markup in the document) etc. I'd rather leave it as it is, with a link or instructions online.

What I'd really like to see is a page with a few examples, eg. how to skip to the next track using netcat/curl, how to get player state etc. All the details about the CLI can stay where they are. Duplication would kill the effort. We'd rather try to clean up the existing file so it could be converted and updated online automatically.

[sodface]

I started to put some example commands together before noticing you already added a reference page, which seems nice and covers everything I was going to do (curl, wget, nc examples). What do you think it's missing?

The only extra thing I was thinking about mentioning was the difference in behavior of the various nc implementations, though I'm not sure I fully understand the nuances enough to correctly explain it in writing. For example, busybox nc always exits when feeding commands to stdin, often before the reply is received and written to stdout, so doing something like this can help if you are trying to capture the response:

{ printf "c0:25:a5:ab:cd:ef status - 10\n"; sleep .1; } | busybox nc 192.168.1.1 9090

And openbsd netcat does sort of the opposite, staying connected after the command when you probably don't want it to. Adding -N helps here:

printf "c0:25:a5:ab:cd:ef status - 10\n" | nc -N 192.168.1.1 9090

Not sure if that's worth wading into or not?

Also, the IP in this example is missing an octet:

https://github.com/LMS-Community/lms-community.github.io/blob/5308de908008684e6dd7d43f18d495c8001e38af/docs/reference/using-the-cli.md?plain=1#L32

[michaelherger]

I believe the busybox netcat is a special case, as most of the busybox tools come with a reduced/different feature set. We should not really handle this here, but probably leave a note saying that it can be different, in particular on pCP.

[michaelherger]

Oh, and thanks for the heads up about the IP address. Should be fixed shortly.

[terual]

I guess now that Daksol's PR (https://github.com/LMS-Community/lms-community.github.io/pull/24) is merged this can be closed. Thanks @Daksol!

[Daksol]

Note on migration of the CLI related material.

Source was LMS version 8.5

https://github.com/LMS-Community/slimserver/blob/79a893c724015ad4f5871beec711d454f599073d/HTML/EN/html/docs/cli-api.html

Migrated content:- Target was this set of files in the lyrion.org repository

• Introduction
• Using the CLI
• General: general management of the Command Line Interface and of the server.
• Players: management of players.
• Database: mangement of the music database.
• Playlist: management of the playlist of each player.
• Coumpound Queries: queries to get most of the information about the server or a player in one convenient query, that can be updated by the server automatically.
• Notifications: internal server commands echoed to the CLI by using the "listen" or "subscribe" commands.
• Alarms: management of alarms.

Not migrated content

Two chunks of content from the original file were NOT migrated. For clarity the html of those sections included in this comment as zipped html attachments:-

• Plugins - cli-api-plugins.html.zip cli-api-plugins.html.zip
• Deprecated cli-api-deprecated.html.zip cli-api-deprecated.html.zip