Kitten

Reference sections

Use the kitten help command to access command information from your terminal.

To get detailed help on a specific command, use kitten help <command name>. For example, kitten help serve.

You can also pass the --help or -h option to any command to get more detailed information about it. So kitten serve --help is equivalent to kitten help serve.

If you have the kitty terminal installed, be aware that it includes a tool also named kitten. This can cause conflicts with the kitten CLI tool, as both share the same name. As a result, they may interfere with each other, and you may find it difficult to launch the correct tool.

In such a situation, you can always start Kitten using the full path to Kitten – ~/.local/bin/kitten – or create an alias/symbolic link to it with a different name.

kitten [path to serve] [options]
kitten serve [path to serve] [options]

Serves a Kitten place.

💡 If you do not specify a path to serve, the default directory (./) is assumed.

When running multiple Kitten instances to test peer-to-peer web functionality during development, remember to use a different domain and port for each instance (for example, place1.localhost for one and place2.localhost:444 for the other) to ensure that sessions work correctly.

This is because Kitten sessions make use of cookies and cookies do not provide isolation by port.

Kitten supports four localhost subdomains (place1 to place4) that can be run on any valid port for testing peer-to-peer Small Web apps locally.

An app running on a random port gets a random data directory assigned to it. This directory is only valid for as long as the server is up. The next time you run the same app from a random port, it will get a different data directory and the data from the first run will not carry over. In other words, do not run your app on a random port if it uses a database and relies on data persistence between runs.

The random port feature is useful for local web apps that run locally on your device (the equivalent of command-line applications or native apps).

e.g., see the Markdown Preview utility in the examples folder.

Small Web apps are not meant to be run from random ports on production machines. Always deploy to run from port 443 in live environments (e.g., a VPS or a dedicated device like a single-board computer connected to your home router).

kitten init [language]

Initialises a type-safe Kitten project in the current folder. The language argument is either js or ts (the default).

The kitten init command:

It skips any file that already exists. (See Type safety.)

kitten add [aspect]

Adds an aspect to the project in the current folder. The only aspect is type safety, which you can call types (the default), type-safety, or kitten-types.

The kitten add types command does the type safety part of the kitten init command only: it doesn’t add the engines.kitten field or any of the other project files. It sets up a JavaScript project if the folder has a jsconfig.json file and no tsconfig.json file, and a TypeScript project otherwise. (See For an existing project under Type safety.)

kitten check [path]
kitten check [path] --fix [id]

Checks your app’s source code for what you must change to run it on the Kitten you have installed, and lists each finding with the change to make. The path argument defaults to the current folder. Run it before you move an existing app to a new Kitten API version (see Versioning).

The kitten check command checks the files that Kitten serves (see Valid file types), and your app modules. Markdown pages and fragments go through the same transform that Kitten’s loader uses. It never imports or runs your code. Instead, it parses it and renders each template with Kitten’s own kitten.html and probe values, so it reports what the renderer refuses or escapes. (The kitten check command doesn’t check types. If your package.json has a typecheck script, run npm run typecheck for that.)

Each finding is one of three kinds:

Each finding starts with an emoji for its kind (📝 for a notice, 🟠 for a warning, and ❌ for an error), its kind, the ID of its check, and its file, line, and column, followed by the change to make and a link to the change log entry or reference section that describes it. Where Kitten can’t be sure of the line (e.g., in the text of a Markdown page), it gives the file alone.

After the counts, Kitten reports how many findings the --fix option can fix, or that it can’t fix any of them.

The kitten check command exits with 1 when it reports an error. It also exits with 1 when it can’t run (e.g., for a path that doesn’t exist, the root or home folder, an unknown check ID, an unknown option, or a --fix it refuses). It exits with 0 otherwise, so you can run it in continuous integration.

Kitten shows every finding, whatever your package.json declares in its engines.kitten field. This means that a notice can still appear once you’ve made the change it describes, as Kitten can’t tell from the code that you’ve looked at it. (Notices never change the exit code.)

These checks link here, as no change log entry describes them:

Pass the --only <id> option to run one check.

Pass the --fix option to apply the fixes of the checks that have them (icon-pascal-case, safely-add-html-renamed, and introspection-prefix), or --fix <id> to apply the fixes of one check. (Put the folder first, as in kitten check <folder> --fix <id>, or Kitten reads the folder as the ID.) Kitten then runs the checks again and prints that report.

The --fix option changes a file only when its content is committed in Git, i.e., equals the file’s version in HEAD, so git checkout HEAD -- <file> undoes the fix. Otherwise, it lists the files and changes nothing. Pass the --allow-uncommitted option to change uncommitted files too. Whatever you pass, the --fix option:

Run the database commands from your app’s folder. They open the databases of the app in that folder as served at localhost, port 443 (the defaults of kitten serve). (Pass the --domain and --port options to open the databases of the app as served at another domain or port.)

kitten db [table name]
kitten db info [table name]

Shows database and table information.

kitten db delete [table name]

Deletes either the whole database or the table with the specified table name after asking you for confirmation.

kitten db tail <table name>

Shows a summary of the head (start) and tail (end) of your database table (remember that database tables in JSDB are append-only JavaScript logs) and starts to follow additions to it.

Press Ctrl C to exit as you would a regular shell tail command.

kitten _db [table name]
kitten _db info [table name]
kitten _db delete [table name]
kitten _db tail <table name>

The _db commands work like the db commands, on Kitten’s internal database for your app (kitten._db) instead of your app’s database. The _db command is an alias for _db info, and the _db tail command also takes the --all option.

kitten deploy <git HTTPS clone URL> [options]

Creates a Kitten place by deploying a Kitten project from a git repository as a systemd service.

The kitten deploy command also enables lingering for the account, so the service runs when nobody is logged in; when it cannot, it prints the loginctl command to run.

kitten run <git HTTPS clone URL> [options]

Is the little brother of the deploy command. Runs a Kitten project from a git repository locally as a regular process.

Its options are the same as those of the default serve command, except the --open option.

kitten status

Shows Kitten systemd service status.

kitten logs [options]

Tails (follows) the Kitten systemd service logs using journald.

kitten start

Starts the Kitten systemd service.

kitten stop

Stops the Kitten systemd service.

kitten restart

Stops and then starts the Kitten systemd service. If the service isn’t running, the kitten restart command exits with an error. (Use the kitten start command instead.)

kitten enable

Enables the Kitten systemd service, so it starts when the server boots.

The kitten deploy command enables the service for you, so you only need this command after the kitten disable command. (Enabling doesn’t affect restarts on failure: systemd restarts the service when it fails whether or not it’s enabled.)

kitten disable

Disables the Kitten systemd service, so it no longer starts when the server boots. (It doesn’t stop a running service. Use the kitten stop command for that.)

kitten shell

Opens the interactive shell of the Kitten service running on this machine, by connecting to 127.0.0.1, port 1337. See Connecting to a Kitten service for how to use it from your own machine over SSH.

kitten version
kitten --version
kitten -v

Displays the Kitten version, made up of:

Your app declares the Kitten API version it is written for in its package.json, with "engines": { "kitten": "1" } (the kitten init command adds this for you). A deployed app then follows the newest Kitten release of that API version. Run kitten check before you add it to an existing app. (See Versioning.)

kitten help
kitten help <command name>
kitten <command name> --help
kitten <command name> -h

Use the kitten help command to access command information from your terminal.

To get detailed help on a specific command, use kitten help <command name>. For example, kitten help serve.

You can also pass the --help or -h option to any command to get more detailed information about it. So kitten serve --help is equivalent to kitten help serve.

kitten update
kitten update --api-version=<API version>

On a development machine, the kitten update command installs the newest Kitten release from kittens.small-web.org. With the --api-version option, it installs the newest release for that API version. When the release is older than the installed Kitten, it asks before downgrading.

On a server with a deployed app, the kitten update command checks for an update as Check now on the Kitten Settings page does: it chooses the Kitten release and the app commit to install (see Versioning), restarts the service, and waits for the outcome. It exits with 0 when the update is confirmed or nothing is newer, 1 when it was rolled back or could not be prepared, and 2 when another update is in progress or the outcome is not known in time; the kitten logs command shows the server’s progress. On a server, the kitten update command refuses the --api-version option.

Note that the kitten update command runs its own update check beside the server’s, and if the two overlap, Kitten may not be able to roll the update back. So, while automatic updates are on, use Check now on the Kitten Settings page instead.

The downgrade prompt shows when the installed Kitten is more recent than the release: a development build, or an API version later than the one you pass.

kitten uninstall

Uninstalls Kitten after asking for confirmation.

The kitten uninstall command:

It doesn’t remove your apps’ data, including their databases (in ~/.local/share/small-tech.org/kitten/data), deployed apps (in ~/.local/share/small-tech.org/kitten/deployments), apps you’ve run with kitten run (in ~/.local/share/small-tech.org/kitten/clones), or the Let’s Encrypt certificates for your domains (in ~/.local/share/small-tech.org/kitten/tls/global). Delete these folders yourself if you don’t need them anymore.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.