Command Line Interface

The Jot CLI client is the primary interface with a Jot server. It's used for everything from uploading and verifying files, to server moderation.

Introduction

The CLI has the following commands which we'll go over below:

$ jot --help
Usage: jot [OPTIONS] [COMMAND]

Commands:
  config  Show config
  fetch   Fetch a file from the remote server
  init    Initialize a signing key & directory
  keys    List the known keys
  ls      List the objects on the remote server
  rm      Remove a file
  sign    Sign something with a Jot key
  upload  Upload a file
  verify  Verify a signature
  watch   Watch workdir files and upload any changes
  help    Print this message or the help of the given subcommand(s)

Options:
  -l, --log-level <LOG_LEVEL>  Turn set log level
  -h, --help                   Print help
  -V, --version                Print version

config

The config command can show the client or server configuration for your site after parsing config files, CLI args, environment vars, and setting defaults.

config client

Here's an example of client configuration:

$ jot config client
{
  "admin_key_id": null,
  "mod_key_id": null,
  "log_level": "warn",
  "key_directory": "/home/treadful/.config/jot-client/keys",
  "default_server": "public",
  "servers": {
    "public": {
      "base_uri": "https://jot.run"
    }
  }
}

admin_key_id and mod_key_id are the keys to use for admin or moderator actions. Most users will have null for these fields.

log_level sets how much logging the client should do. Valid values are trace, debug, info, warn, error.

key_directory is where the client stores all keyfiles.

default_server is the server the Jot client will interact with if not specified via a CLI arg. And servers is a map of servers the client can connect to. They key of the map is what's used for CLI args. For instance, jot config server -s public ~6f03ea78.

config server

All server configuration is set during key registration (See: jot init) And here's an example of server configuration:

$ jot config server ~6f03ea78 
{
  "key_id": "036f03ea78158185eff86f624ce1966ddea3a0e4607156a076e22a7251e94d652e",
  "config": {
    "alias": "treadful",
    "domain": "treadful.dev",
    "expire": 0,
    "on_no_index": "Configured",
    "index_file": "index.md"
  }
}

key_id is the full encoded public key as the server knows it. config contains site configuration:

alias is primarily used for subdomains on jot.run. In this case, this site will render at treadful.jot.run.

domain is a custom domain, that when pointed at the Jot server, will return this site. In this case, treadful.dev. See Domains for more information.

expire is the set expiration for this site and all its files. NOTE: This feature is not fully implemented on the server at jot.run. See Issue #140 for more information.

on_no_index is what the server does when it cannot find the default index file index.md.

index_file is what file the server should use by default at the root of the site.

fetch

The fetch command is used to update your local filesystem with files from the server. This is primarily useful if you run updates from multiple systems or if you're migrating to a new workstation. By default, the client will not update local files if they already exist.

$ jot fetch --overwrite ~/jot/treadful/styles.css 
Fetching https://jot.run/~6f03ea78/styles.css

init

The init command is used to initially generate your key pair and register with the server. It is also used to update existing key configuration if needed.

--alias is primarily used for subdomains on jot.run. In this case, this site will render at treadful.jot.run.

--domain is a custom domain, that when pointed at the Jot server, will return this site. In this case, treadful.dev.

--expire is the set expiration for this site and all its files. NOTE: This feature is not fully implemented on the server at jot.run. See Issue #140 for more information.

--on-no-index instructs the server on what to do when it cannot find the default index file index.md. By default, it will show a file list of the directory.

--index-file is what file the server should use default at the root of the site.

--encrypt will locally encrypt your keyfile using a provided passphrase. You will need to enter this passphrase every time the key is needed.

Re-run this command whenever you need to change your configuration.

keys

The keys command will show all keys known to the client. It will display the public key, the short ID, and the local directory for each key.

$ jot keys 
036f03ea78158185eff86f624ce1966ddea3a0e4607156a076e22a7251e94d652e(~6f03ea78): /home/treadful/jot/treadful

ls

ls will list all files on the remote server for the given key.

$ jot ls ~6f03ea78
/home/treadful/jot/treadful/index.md
/home/treadful/jot/treadful/notes/ssh_tunnels.md
/home/treadful/jot/treadful/styles.css
/home/treadful/jot/treadful/tread_bg.jpg
/home/treadful/jot/treadful/log/20260616-ironfox_slow.md
/home/treadful/jot/treadful/pgp-key.txt

rm

rm will remove a file from the local directory as well as the remote server (unless --keep-local is used).

$ jot rm ~/jot/treadful/test.txt
Deleting /home/treadful/jot/treadful/test.txt using key ~6f03ea78

sign

The sign subcommand allow you to use your key to sign files or other messages. This can be useful for signature proofs where you do not want to leverage a Jot server.

Here's an example signing a file:

$ jot sign ~6f03ea78 file /tmp/test.txt
Signature: 545194d6a5b8948217861a6c56dfd02fb0d55870afd6bbc726fe91060306553519af50aa2f1bdeef876e10321711104130e8988fda3c23fa661395649fc83c3401

And signing a text string:

$ jot sign ~6f03ea78 msg "do not trust - invalid"
Signing msg: 'do not trust - invalid'
Signature: d3ae3b04d0c41962d2c2619a8fdf48ce96cf98cb9ee6cb3640c80317b3b741563cdf11638e30431c212c6a5c12834864eb201f3c084ad8e9a588f6a394dee61401

See verify to verify these signatures.

upload

upload is likely to be your most used command. It uploads files from your key's local directory to the server.

$ jot upload ~/jot/treadful/index.md 
Successfully uploaded https://jot.run/~6f03ea78/index.md

verify

The verify command is the compliment to sign and can also be used to verify signatures of files uploaded to a Jot server.

Here's an example verifying the signature of the message we signed previously:

$ jot verify msg d3ae3b04d0c41962d2c2619a8fdf48ce96cf98cb9ee6cb3640c80317b3b741563cdf11638e30431c212c6a5c12834864eb201f3c084ad8e9a588f6a394dee61401 "do not trust - invalid"
Recovered key: ~6f03ea78 (036f03ea78158185eff86f624ce1966ddea3a0e4607156a076e22a7251e94d652e)

This will reveal the short ID and public key of the key that signed the file.

And an example verifing the signature of a file (yes, you need this file to verify):

$ jot verify file 545194d6a5b8948217861a6c56dfd02fb0d55870afd6bbc726fe91060306553519af50aa2f1bdeef876e10321711104130e8988fda3c23fa661395649fc83c3401 /tmp/test.txt 
Recovered key: ~6f03ea78 (036f03ea78158185eff86f624ce1966ddea3a0e4607156a076e22a7251e94d652e)

You may also use this command to verify the signatures of files uploaded to a Jot server:

$ jot verify uri https://jot.run/~6f03ea78/index.md
Recovered key: ~6f03ea78 (036f03ea78158185eff86f624ce1966ddea3a0e4607156a076e22a7251e94d652e)

This can be used to prove that files were not modified on the remote server.

watch

The watch command can be used to automatically upload files from the given paths. For instance, jot watch ~/jot/treadful/ will automatically upload any files changed in that key directory.

See File Watching for more information.