Usage

In this section, we will start the server and manage our first process.

Help

To get a list of all the available commands, run:

$ kurv --help # or just kurv

Version

To get the version of the binary, run:

kurv --version

Start the server

To get the server rolling, type:

kurv server

Important

kurv will create a file called .kurv where it will store the current state of the server. The file will be created in the same directory where the binary is located or in the path specified by the KURV_HOME_KEY environment variable.

since kurv can be used both as a server and as a client, if you want to run it as a server, you need to set the KURV_SERVER environment to true. This is just a safety measure to prevent you from running the server when you actually want to run the client. To bypass this, you can use the --force flag (kurv server --force)

Collect some eggs 🥚!

To deploy/start/daemonize an app (collect an egg), do:

kurv collect path/to/egg-config.egg

The path should point to a YAML file that contains the configuration for the egg.

It should look something like this:

name: fastapi # the name of the egg / should be unique
command: poetry # the command/program to run
args: # the arguments to pass to the command
  - run
  - serve
cwd: /home/user/my-fastapi-app # the working directory in which the command will be run
env: # the environment variables to pass to the command
  FASTAPI_PORT: 8080

This will run the command poetry run serve in /home/user/my-fastapi-app with the environment variable FASTAPI_PORT set to 8080.

If for some reason, the command/program crashes or exits, kurv will revive it!

Show me my eggs

If you want a summary of the current state of your eggs, run:

$ kurv list

🥚 eggs snapshot

╭───┬───────┬───────────┬─────────┬───┬────────╮
│ i │ pid   │ name      │ status  │ ↺ │ uptime │
├───┼───────┼───────────┼─────────┼───┼────────┤
│ 1 │ 35824 │ fastapi   │ running │ 0 │   1s   │
│ 2 │ 0     │ fastapi-2 │ stopped │ 0 │   -    │
╰───┴───────┴───────────┴─────────┴───┴────────╯

For details on a specific egg:

$ kurv egg <egg:name|id|pid>

This will show you the egg’s configuration, process details, etc.

Stop an egg

To halt an egg without removing it:

$ kurv stop <egg:name|id|pid>

This will stop the process but keep its configuration in the basket in case you want to start it again later.

Remove an egg

To actually remove an egg, run:

$ kurv remove <egg:name|id|pid>

It will stop the process and remove the egg from the basket.

Restart

If you need the process to be restarted, run:

$ kurv restart <egg:name|id|pid>

Environment variables

You can update / replace the environment variables of a running egg with:

$ kurv env <egg:name|id|pid> path/to/env-file.json

The env-file.json should be a JSON file with key-value pairs representing the environment variables.

{
  "FASTAPI_PORT": "9090",
  "ANOTHER_ENV_VAR": "some_value"
}

The kurv env command accepts a --replace flag that, when set, will replace the entire environment of the egg with the new variables from the file. If not set, it will merge the new variables with the existing ones.

Important
Changes in environment variables will only take effect after restarting the egg.

Plugin System 🔌

Want to extend kurv with your own tools? Kurv support plugins! They’re special eggs that kurv automatically discovers and manages.

How it works

Drop an executable starting with kurv- in <KURV_HOME>/plugins/
Make it respond to --kurv-cfg with JSON config, same as an egg config
Restart kurv server
That’s it! The plugin is now running 🎉

View your plugins:

$ kurv plugins # list all plugins

Plugins can be started, stopped, and restarted just like regular eggs, but they can’t be removed (stop kurv and delete the executable instead).