@kluai/cli

This project provides a CLI for interacting with the Klu API.

It offers both the ability to configure your applications and actions using declarative YAML files, and the ability to interact with your workspace using interactive and non-interactive commands.

Features

• Configure apps and actions using declarative YAML files.
• Manage providers, models, apps and actions.
• Pipe inputs into your actions.
• View account details and usage.

Usage

Installation

Before installing the CLI, you'll need to make sure you are running at least Node.js v20.9.0. We recommend using Volta to manage your Node.js versions and volta install to install any global tool binaries.

# Install the CLI using npm
npm install -g @kluai/cli

# -- OR --

# Install the CLI using Volta
volta install @kluai/cli

Setting up your workspace

You'll also need to sign up for a Klu account and to create a workspace if you haven't already done so.

Once you've created a workspace and installed the CLI, to get started using the CLI you'll need to authenticate it to a workspace using a Klu API key. You can run klu to do this. After that's done you'll be logged into that workspace and able to run commands against it.

If you're using this workspace for the first time, there's a helpful klu init command that can setup your workspace for you. Running this will create klu-app-<app-name>.yaml files at the current working directory of your local machine describing the desired state of your remote Klu workspace. You'll want to change your working directory to a suitable location before running this command.

If you already have prompts defined within a TypeScript app it'll even help you to migrate these into this local workspace. Just run klu init --with-migrate <project-dir> and follow the instructions (or klu migrate --include <dir|glob> if you only want to migrate prompts).

# Authenticate to a workspace
klu

# Initialize the workspace locally, migrating any prompts found within the project
klu init --with-migrate <project-dir>

Working with a local workspace

It's possible to run commands that directly alter your remote workspace and a full list of commands can be found if you run klu help. However, the easiest way to manage your Klu workspace is locally through declarative app files that can be "pushed" and "pulled" from it.

Assuming you've already initialized your local workspace, below is a cheatsheet of how to add new apps and actions to it and how to upload your local changes to the remote workspace once you're happy with them.

# Pull the latest changes from the remote workspace
klu pull --yes

# Scaffold a new app
klu scaffold app --name <app-slug> --yes

# Scaffold a new action within the app you created
klu scaffold action --app <app-slug> --action-type chat --name <action-slug> --model gpt-4 --yes

# Edit a local copy of an app using your default editor
# Please ensure that your $VISUAL or $EDITOR env vars are set
klu app edit <app-slug> --no-push

# Check your local changes against the remote workspace
klu push --dry-run

# Push your local changes to the remote workspace
klu push --yes

IMPORTANT:

When using klu push you are responsible for ensuring that the system reaches its desired state:

1. Before making any changes, use klu pull first to ensure your local workspace is synchronized with the server.
2. Carefully check your changes before applying them.
3. In the result of an error or conflict, it is safe to retry the push but you may need to manually resolve any issues first.
4. We strongly recommend against having multiple users working on the same workspace at the same time, as this may result in conflicts and we do not yet have inbuilt support for concurrency or conflict resolution.

Deploying and prompting actions

Of course, once you've created your first action, you'll want to test that it works. Before doing so you'll need to deploy your action into an environment. Once this is done, you can prompt it directly for the command line to test it by hand.

# Deploy an action first before you use it
klu action deploy <action-slug> --environment staging

# Start an interactive session with an action
klu action prompt <action-slug> --interactive

# Prompt an action and stream its output
klu action prompt <action-slug> --input "Write a short simplistic lullaby for a little program that does their best."

# Prompt an action asynchronously in the background
klu action prompt <action-slug> --input "Write a haiku." --json --async

NOTE:

The Klu CLI has a built-in way to quickly prompt the default model directly from the command line and there are also aliases provided to access this even easier. If you want to install the aliases run klu prompt --install from your terminal and then once this is done and your shell has been restarted you should be able to access the quick prompting feature anywhere you need it by calling ? (e.g. ? tell me a joke or cat package.json | ?).

Managing your models

# View account details
klu account

# List available model providers
klu providers

# Create a new models provider
klu provider create --provider-name OpenAI --api-key $OPENAI_API_KEY --is-default-provider --yes

# List available models
klu models

Misc

There are also a number of other commands that can interact with your workspace non-interactively. These can be used to enable advanced scripting through command composition.

# List the GUIDs of all your apps
klu apps --json | jq '.[] | .guid'

# Create a new app
klu app create --name "My App" --description "My app description" --yes

# Get a cow to say the names of each of your apps
klu apps --json | jq -r '[.[] | .name] | join(", ")' | cowsay

Running these commands will not automatically update any local .yaml configuration files on your machine. Therefore, we recommend that you call klu pull --yes to synchronise your local workspace with the remote server after making any changes.

See klu help for all available commands and options.

Development

We use volta to automatically load the correct node and yarn version.

To setup volta

# Install Volta
curl https://get.volta.sh | bash

# Configure your shell to use Volta
volta setup

# Either restart your shell or run the following command
exec $SHELL -l

Install dependencies and run the CLI

# Install dependencies
yarn

# Run the CLI
yarn klu