Qelos CLI

A command-line interface to help you create and manage your Qelos plugins.

Installation

Global Installation

Install the CLI globally using npm:

npm install -g @qelos/plugins-cli

After installation, the CLI will be available as both qelos and qplay commands:

qelos --version
qplay --version

Environment Variables

The CLI requires the following environment variables to connect to your Qelos instance:

• QELOS_URL - Your Qelos instance URL (default: http://localhost:3000)
• QELOS_USERNAME - Your Qelos username (default: [email protected])
• QELOS_PASSWORD - Your Qelos password (default: admin)

You can set these in your shell profile or use a .env file:

export QELOS_URL=https://your-qelos-instance.com
export QELOS_USERNAME=your-username
export QELOS_PASSWORD=your-password

Commands

Create a new plugin

Create a new plugin project:

qplay create my-app

Pull

Pull resources from your Qelos instance to your local filesystem. This allows you to work on components, blueprints, configs, plugins, blocks, integrations, and connections locally.

Syntax:

qelos pull <type> <path>

Arguments:

• type - Type of resource to pull (e.g., components, plugins, integrations, connections, blueprints)
• path - Local directory path where resources will be saved

Example - Pull Components:

qelos pull components ./my-components

This command will:

1. Connect to your Qelos instance using the configured credentials
2. Fetch all components from the instance
3. Create the target directory if it doesn't exist
4. Save each component as a .vue file using its identifier as the filename
5. Display progress for each component pulled

Output:

Created directory: ./my-components
Found 5 components to pull
Pulled component: header-component
Pulled component: footer-component
Pulled component: sidebar-component
All 5 components pulled to ./my-components

Push

Push local resources to your Qelos instance. This allows you to update or create components, blueprints, configs, plugins, blocks, integrations, and connections from your local filesystem.

Syntax:

qelos push <type> <path>

Arguments:

• type - Type of resource to push (e.g., components, plugins, integrations, connections, blueprints)
• path - Local directory path containing the resources to push

Example - Push Components:

qelos push components ./my-components

This command will:

1. Connect to your Qelos instance using the configured credentials
2. Read all .vue files from the specified directory
3. For each file:
   • Check if a component with the same identifier exists
   • Update the existing component or create a new one
   • Display progress for each component

Output:

Pushing component: header-component
Component updated: header-component
Pushing component: new-component
Component pushed: new-component
All components pushed

Agent

Interact with AI agents using the Qelos SDK directly from your command line.

Syntax:

qelos agent [integrationId] [options]

Arguments:

• integrationId - Integration ObjectId or name (case-insensitive)

Key Options:

• -m, --message - Message to send (or pipe from stdin)
• -s, --stream - Real-time streaming responses
• -j, --json - JSON output format
• -l, --log - Maintain conversation history in file
• -e, --export - Save response to file
• -t, --thread - Thread ID for conversation continuity
• -c, --context - JSON string to inject context into the conversation
• --context-file - Path to a JSON file with context to inject
• --tools - Enable built-in terminal tools for the agent (bash, node, read, write)
• -i, --interactive - Keep session alive for multi-turn chat (implies --stream)
• -V, --verbose - Detailed logging

Integration Identification:

You can specify integrations in two ways:

1. Using ObjectId (24-character hex string):

   qelos agent 692876602b6e9881b2311514 --message "Hello"

2. Using Integration Name (case-insensitive):

   qelos agent moshe --message "Hello"

When using a name, the command automatically searches for an integrations folder in the current directory and up to 5 parent directories, looking for .integration.json files with matching trigger.details.name fields.

Examples:

Basic usage with integration name:

qelos agent moshe --message "Hello, how are you?"

Using ObjectId:

qelos agent 692876602b6e9881b2311514 --message "Hello"

From stdin:

echo "What's the weather?" | qelos agent moshe

Streaming with export:

qelos agent moshe --stream --export response.txt --message "Tell me a story"

Conversation logging (maintains context across messages):

echo "My name is David" | qelos agent moshe --log chat.json
echo "What's my name?" | qelos agent moshe --log chat.json

JSON output:

qelos agent moshe --json --export api.json --message "API info"

Thread support:

qelos agent moshe --thread thread-123 --message "Continue conversation"

Verbose mode (shows name resolution process):

qelos agent moshe --verbose --message "Show me your verbose output"

Features:

• Smart Integration Resolution: Use either ObjectIds or integration names
• Conversation History: Maintain context across multiple messages with --log
• Streaming Support: Real-time response streaming with --stream
• Export Options: Save responses in various formats with --export
• Thread Support: Continue specific conversation threads with --thread
• Flexible Input: Use --message flag or pipe from stdin

Log File Format: Conversation logs are stored as JSON arrays:

[
  {
    "role": "user",
    "content": "Hello, my name is David"
  },
  {
    "role": "assistant", 
    "content": "Hello David! Nice to meet you."
  }
]