Composable Documentation

Composable CLI

This is a command line application that can be used to access your Composable projects. It was designed to fulfill the following main use cases:

  • List and switch between your Composable projects
  • List the existing interactions and execution environments
  • Run interactions once or multiple times over a set of different data inputs
  • Generate data inputs to run the interactions against
  • Search through the history of runs to inspect detailed results

Requirements

A TTY terminal and Node.js version 18 or higher is required.

Installation

npm -g install @composableai/cli

Basic Usage

cpcli help

You need to pass an API KEY to access an organziation (i.e. account) you created in Composable Studio. API KEYs are created at the organziation level and can be found in the settings of your organization.

Let's list all the projects in the organization owning the API KEY:

cpcli -k {YOUR_API_KEY} projects

To access a project you must pass the project ID too. Let's list the Interactions inside a project:

cpcli -k {YOUR_API_KEY} -p {PROJECT_ID} interactions

To simplify using the CLI command options which can get quite long, you can create profiles to store common arguments like the API key, the target project or the target server.
Read more about this in config command.

Options and commands

cpcli [options] [command]

  • Name
    -V, --version
    Type
    boolean
    Description

    Display the CLI version.

  • Name
    -k, --apikey
    Type
    string
    Description

    The API key to use for authentication. Required when not using a profile.

  • Name
    -p, --project
    Type
    string
    Description

    The ID of the target project.
    Required when not using a profile for all commands that needs to access a project resources.

  • Name
    -s, --server
    Type
    string
    Description

    The server to connect to. Defaults to https://api.composableprompts.com.

  • Name
    -h, --help
    Type
    boolean
    Description

    Display the help of the current command.

help [command]

Display the help screen. When a command name is specified it will display the help of that command.

upgrade

Check for updates and upgrade the CLI if a new version is available.

config

A command with subcommands to manage configuration profiles.
If used by itself it will print the list of defined profiles with the current active profile highlighted.

config show [name]

If the name is not specified then show all the configuration profiles (as JSON), otherwise show only the given profile (as JSON).

config use <name>

Switch to another configuration profile given its name.

config add

Add a new configuration profile.
This will show interactive prompts to fill in the profile properties.

config edit <name>

Edit an existing configuration profile.
The same interactive prompts will as for the add command will be shown.

config delete <name>

Delete an existing configuration profile given its name.

projects

List the projects you have access to. The current project if any will be highlighted.

envs [envId]

If an environemnt ID is specified then show the environment details, otherwise list all the envirobnments in the current project.

interactions [interactionId]

If an interactionId is specified then show the itneraction details, otherwise list the interactions available in the current project.

run [options] <interactionId>

Run an interaction given the ID.

Options

  • Name
    -i, --input [file]
    Type
    file
    Description

    The input data if any. If no file path is specified it will read from stdin.

  • Name
    -o, --output [file]
    Type
    file
    Description

    The output file if any. If not specified it will print to stdout.

  • Name
    -d, --data [json]
    Type
    string
    Description

    Inline data as a JSON string. If specified takes precendence over --input.

  • Name
    -T, --tags [tags]
    Type
    string
    Description

    A comma separated list of tags to add to the execution run.

  • Name
    -t, --temperature [temperature]
    Type
    number
    Description

    The temperature to use (a number between 0 and 1). Defaults to 0.7.

  • Name
    -m, --model [model]
    Type
    string
    Description

    The model to use. Defaults to the default model of the interaction.
    If no model is specified and the interaction has no default model then the command will fail.

  • Name
    -e, --env [environmentId]
    Type
    string
    Description

    The environment ID to use. Defualts to the default environemnt of the interaction
    If no environment is specified and the interaction has no default environment then the command will fail.

  • Name
    -S, --no-stream
    Type
    boolean
    Description

    If used the output will be printed only when the execution is complete. No streaming will be done. This flag has effect only if a single run is executed. For multi-runs the output is always printed at the end.

  • Name
    -c, --count [count]
    Type
    number
    Description

    The number of times to run the interaction. Defaults to 1.
    If specified must be a positive integer.

  • Name
    -v, --verbose
    Type
    boolean
    Description

    This flag has no effect in streaming mode.
    If used, instead of printing a progress it will print details about each executed run.

  • Name
    --jsonl
    Type
    boolean
    Description

    Write output in jsonl. The default is to write the result as JSON.
    Ignored in streaming mode.

  • Name
    --data-only
    Type
    boolean
    Description

    Write down only the data returned by the LLM and not the entire execution run. Defaults to false in non streaming mode.
    In streaming mode this flag is true by default and cannot be changed.

runs [options] [interactionId]

Search the runs given a search criteria. If an interaction ID is specified then only the runs of that interaction will be returned.

Options

  • Name
    -t, --tags [tags]
    Type
    string
    Description

    A comma separated list of tags to filter the run history

  • Name
    --status [status]
    Type
    string
    Description

    A status to filter on. Can be one of: created, processing, completed or failed

  • Name
    -e, --env [environmentId]
    Type
    string
    Description

    An environment ID to filter on.

  • Name
    -m, --model [model]
    Type
    string
    Description

    A model to filter on.

  • Name
    -q, --query [query]
    Type
    string
    Description

    A lucene query to filter the run history

  • Name
    --before [date]
    Type
    ISO date
    Description

    Filter runs before the given date. The date must be in ISO format

  • Name
    --after [date]
    Type
    ISO date
    Description

    Filter runs after the given date. The date must be in ISO format

  • Name
    -l, --limit [limit]
    Type
    number
    Description

    The maximum number of runs to return in a page (i.e. the page size). Defaults to 100

  • Name
    -P, --page [page]
    Type
    number
    Description

    The page number to return (starting from 0). Defaults to 0.

  • Name
    -f, --format [format]
    Type
    string
    Description

    The output format. One of json, jsonl or csv. Defauilts to json.

  • Name
    -o, --output [file]
    Type
    file
    Description

    A file to save the search result into. If not specified the result is printed to stdout.

datagen [options] <interaction>>

Generate test input data given an interaction ID. The data will be generated by a LLM as specified by the environment and model options.

Options

  • Name
    -e, --env [envId]
    Type
    string
    Description

    Required. The environment ID to use to generate the test data.

  • Name
    -m, --model [model]
    Type
    string
    Description

    The model to use to generate the test data.
    If the selected environment has a default model then this option is optional.

  • Name
    -t, --temperature [value]
    Type
    number
    Description

    The temperature used to generate the test data. Should be a number between 0 and 1. Defaults to 0.7.

  • Name
    -o, --output [file]
    Type
    file
    Description

    A file to save the generated test data. If not specified the data will be printed to stdout.

  • Name
    -c, --count [value]
    Type
    number
    Description

    The number of data objects to generate. Defaults to 1.

  • Name
    -m, --message [value]
    Type
    string
    Description

    An optional message

codegen [options] [interaction]

Generate interaction classes. If an interaction class name is specified then only the class for that interaction will be generated, otherwise the classes for all the interactions in the project will be generated.

Options

  • Name
    --versions [versions]
    Type
    string
    Description

    A comma separated list of version selectors to include. A version selector is either a version number or one of the draft or latest keywords.
    Defaults to "draft,latest".

  • Name
    -a, -all
    Type
    boolean
    Description

    When used, all the interaction versions will be included for code generation.

  • Name
    -d, --dir [file]
    Type
    file
    Description

    The directory where to create the generated class filed. Defaults to ./interactions.

  • Name
    -x, --export <version>>
    Description

    The version to re-export from index.ts. If not specified, the latest version will be exported or if no version is available, the draft version will be exported.

pk [options] [projectId]

Get or create a public API key associated with the account owning the current API key. The current API key must have at least the "application" role.
If a projectId is specified, then, the key will be associated to that project. .option('--name [name]', 'An optional name for the generated key. If not specified a name will be generated.') .option('--ttl [ttl]', 'A ttl value in seconds to be used to expire the generated key. The default is 24h.')

Options

  • Name
    --name [name]
    Type
    string
    Description

    An optional name for the generated key. If not specified a name will be generated.

  • Name
    --ttl
    Type
    integer
    Description

    A time to live in seconds. The key will be expired after the given number of seconds.
    The default value is 24 hours.

Read more about code generation and the anatomy of the generated classes

Was this page helpful?