casualos

CasualOS CLI

Installation

Install to your global package directory:

$ npm install -g casualos

Or, execute directly from NPM:

$ npx casualos

Usage

Usage: casualos [options] [command]

A CLI for CasualOS

Options:
  -V, --version                        output the version number
  -e, --endpoint <url>                 The endpoint to use for queries. Can be used to override the current endpoint.
  -h, --help                           display help for command

Commands:
  login                                Login to the CasualOS API
  logout                               Logout of the CasualOS API
  set-endpoint [endpoint]              Set the endpoint that is currently in use.
  status                               Get the status of the current session.
  query [options] [procedure] [input]  Query the CasualOS API
  repl [options]                       Start a REPL for the CasualOS API
  generate-server-config [options]     Generate a server config for CasualOS.
  validate-server-config [options]     Validate a server config for CasualOS.
  help [command]                       display help for command

Commands

login

$ casualos help login

Usage: casualos login [options]

Login to the CasualOS API

Options:
  -h, --help  display help for command

logout

$ casualos help logout

Usage: casualos logout [options]

Logout of the CasualOS API

Options:
  -h, --help  display help for command

set-endpoint

$ casualos help set-endpoint

Usage: casualos set-endpoint [options] [endpoint]

Set the endpoint that is currently in use.

Arguments:
  endpoint    The endpoint to use for queries. If omitted, then you will be prompted to enter an endpoint.

Options:
  -h, --help  display help for command

query

$ casualos help query

Usage: casualos query [options] [procedure] [input]

Query the CasualOS API

Arguments:
  procedure        The procedure to execute. If omitted, then you will be prompted to select a procedure.
  input            The input to the procedure. If specified, then it will be parsed as JSON. If omitted, then you will be prompted to enter the input.

Options:
  -k, --key <key>  The session key to use for the query. If not specified, then the current session key will be used.
  -h, --help       display help for command

repl

$ casualos help repl

Usage: casualos repl [options]

Start a REPL for the CasualOS API

Options:
  -k, --key <key>  The session key to use for the session. If omitted, then the current session key will be used.
  -h, --help       display help for command

The CasualOS REPL allows you to interact with the CasualOS API using a Read-Eval-Print Loop (REPL).
It supports JavaScript and has a special function, query([procedure], [input]), that can be used to query the API.

generate-server-config

$ casualos help generate-server-config

Usage: casualos generate-server-config [options]

Generate a server config for CasualOS.

Options:
  -p, --pretty  Pretty print the output.
  -h, --help    display help for command

validate-server-config

$ casualos help validate-server-config

Usage: casualos validate-server-config [options]

Validate a server config for CasualOS.

Options:
  --json <config>    The JSON to validate.
  -f, --file <file>  The file to validate.
  -h, --help         display help for command

REPL Usage

The CasualOS REPL allows you to interact with the CasualOS API using a Read-Eval-Print Loop (REPL).

It supports JavaScript and has a special function, query([procedure], [input]), that can be used to query the API. You can access it via the repl command.

After every evaluation, the _ variable will contain the result of the evaluation. Additionally, you can assign values to variables to store them for the entire session.

query([procedure], [input])

The query() function can be used inside a REPL session to query the API of the currently set endpoint. It accepts two optional parameters, procedure and input, and returns a promise that resolves with the result of the query. Because it returns a promise, you can use the await keyword on it to get the result of the query.

• procedure should be a string and is the name of the procedure that should be executed. If omitted, then you will be prompted from a list of available procedures.

• input can be any JavaScript value that matches the schema of the procedure. If omitted, then you will be prompted to fill in values for the procedure input.

To use query() in a REPL session, run await query(). This will start a query and wait until the query has a result. If you already know which operation you want to execute, you can run await query("procedureName"). This will skip the initial selector, but will still prompt you for inputs. If you already have the procedure and inputs, then you can run await query("procedureName", input). This will skip all prompts and will return the procedure result directly back to you.

If you don't provide an input, then query() will automatically prompt you for inputs based on the metadata of the procedure. When answering prompts for query(), you can use a script by entering a . at the start of the input value. This will let you use the result of a JavaScript expression for the value. For example, when entering a string for expireTimeMs, you could write .Date.now() - (1000 * 60 * 60) to calculate 1 hour in the past in miliseconds. If you want to write a string that starts with a period (.), then just write two dots at the start. For example, instead of .myString, you would write ..myString. These special instructions only apply to the query() function inside repl, and not to the query command.

Changelog

V3.3.13

Date: TBD

:rocket: Features

• Added ai.chat.allowedModels feature to enforce model usage limits, restricting access to specific models based on configuration.

• Added shared documents.

  • Shared documents utilize insts to be able to share data without using bots and tags.

  • Additionally, shared documents can be loaded and unloaded at will.

  • The following functions have been added:

    • os.getSharedDocument(name) - Gets a document that is stored in the current inst.
    • os.getSharedDocument(recordName, inst, name) - Gets a document that is stored in the specified inst.
    • os.getLocalDocument(name) - Gets a document that is stored on this device.
    • os.getMemoryDocument() - Gets a document that is stored in memory and cleared upon refresh.

  • Usage:

    // Get a document stored in this inst named "test"
    const doc = await os.getSharedDocument('test');
    
    // maps work like the Map type (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
    const inventory = doc.getMap<number>('inventory');
    
    inventory.set('spoons', 2);
    inventory.set('forks', 3);
    os.log('Number of spoons: ' + inventory.get('spoons'));
    
    // arrays work like regular JavaScript arrays:
    const shoppingList = doc.getArray<string>('shoppingList');
    shoppingList.push('cereal', 'milk', 'eggs');
    
    os.log('Shopping list:', inventory.toArray());
    
    // Text is a special type that makes it easy to work with long strings
    const blogPost = doc.getText('blogPost');
    
    blogPost.insert(0, 'Hello, world!');
    
    os.log('Blog Post:\n', blogPost.toString());