CLI Tool

The Qelos CLI (@qelos/plugins-cli) is a command-line interface tool that helps developers manage and synchronize Qelos resources between their local development environment and their Qelos instance.

Overview

The CLI provides powerful commands to:

• Create new plugin projects with scaffolding
• Get preview files that would be pushed without actually pushing them
• Pull resources from your Qelos instance to work locally
• Push local changes back to your Qelos instance
• Generate IDE-specific rules files for better AI assistance
• Agent interact with AI agents via command line with conversation support
• Manage components, blueprints, configurations, integrations, connections, plugins, and blocks

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

Global Options

These options are available for all commands:

Option	Alias	Type	Description
--verbose	-V	boolean	Run with verbose logging
--env	-e	string	Load .env.[ENV] file (e.g. --env production)
--config	-C	string	Path to config file (auto-discovers by default)
--save	-S	boolean	Save current command options to qelos.config.json
--global	-g	string	Use a registered global environment (see Global Environments). Omit value to use "default".
--help		boolean	Show help
--version		boolean	Show version

Configuration

The CLI supports three layers of configuration, applied in this priority order:

1. CLI flags (highest priority)
2. Environment variables
3. Config file (qelos.config.json / qelos.config.yaml)
4. Built-in defaults (lowest priority)

Environment Variables

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

Variable	Description	Default
QELOS_URL	Your Qelos instance URL	http://localhost:3000
QELOS_API_TOKEN	API token (alternative to username/password)	—
QELOS_USERNAME	Your Qelos username	test@test.com
QELOS_PASSWORD	Your Qelos password	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

API Token Authentication

Instead of username/password, you can use an API token for CLI authentication. This is the recommended approach for CI/CD pipelines and automated workflows.

export QELOS_URL=https://your-qelos-instance.com
export QELOS_API_TOKEN=ql_your_api_token_here

# No username/password needed
qelos pull components ./my-components

When QELOS_API_TOKEN is set, QELOS_USERNAME and QELOS_PASSWORD are not required. The API token takes priority if all three are configured.

You can also set it in the config file:

{
  "qelosUrl": "https://your-qelos-instance.com",
  "qelosApiToken": "ql_your_api_token_here"
}

Create an API token from the Qelos admin UI under Profile → API Tokens. See SDK Authentication for details.

Automatic .env Loading

The CLI automatically loads .env files from the current working directory. No flags are needed — if a .env file exists, it is loaded before any command runs.

The loading order (first file sets the value, later files do not override):

1. .env.local
2. .env

Use the --env flag to load environment-specific files:

# Loads: .env.production.local → .env.production → .env.local → .env
qelos --env production push components ./my-components

# Loads: .env.staging.local → .env.staging → .env.local → .env
qelos --env staging agent code-wizard -m "Hello"

Example .env files:

.env (API Token)

QELOS_URL=https://my-instance.qelos.app
QELOS_API_TOKEN=ql_your_api_token_here

.env (Username/Password)

QELOS_URL=https://my-instance.qelos.app
QELOS_USERNAME=admin@company.com
QELOS_PASSWORD=secret

Config File

The CLI auto-discovers a config file from the current working directory. The following filenames are searched in order:

1. qelos.config.json
2. qelos.config.yaml
3. qelos.config.yml

You can also specify an explicit path with --config:

qelos --config ./my-config.json agent code-wizard -m "Hello"

Config File Schema

qelos.config.json

{
  "qelosUrl": "https://my-instance.qelos.app",
  "agents": {
    "code-wizard": {
      "thread": "persistent-thread-id",
      "log": "./logs/code-wizard.log",
      "export": "./output/response.md",
      "json": false,
      "stream": true,
      "clientTools": ["bash", "read"]
    }
  },
  "dump": {
    "blueprints": {
      "all":      { "path": "./dump", "group": "status" },
      "my-blueprint": { "filter": "{\"active\":true}", "path": "./dump/my-blueprint" }
    },
    "users":      { "path": "./dump" },
    "workspaces": { "path": "./dump" }
  },
  "pull": {
    "components": { "path": "./src/components" },
    "blueprints": { "path": "./blueprints" }
  },
  "push": {
    "components": { "path": "./src/components", "hard": false }
  },
  "restore": {
    "blueprints": {
      "all":          { "replace": false, "path": "./dump" },
      "my-blueprint": { "replace": true, "path": "./dump/my-blueprint" }
    }
  }
}

qelos.config.yaml

qelosUrl: https://my-instance.qelos.app
agents:
  code-wizard:
    thread: persistent-thread-id
    log: ./logs/code-wizard.log
    stream: true
    clientTools:
      - bash
      - read
dump:
  blueprints:
    all:
      path: ./dump

agents — per-agent defaults for qelos agent:

Key	Type	Description
agents[name].thread	string	Default thread ID
agents[name].log	string	Default log file path
agents[name].export	string	Default export file path
agents[name].json	boolean	Default JSON output mode
agents[name].stream	boolean	Default streaming mode
agents[name].clientTools	(string|object)[]	Client-side tools enabled by default for qelos agent. Can include built-in tool names (e.g. "bash") and/or custom tool objects. See Agent Tools.

Config values are used as defaults — CLI flags always take precedence.

Saving Config with --save

Use the --save (-S) flag to persist the current command's options into qelos.config.json:

# Creates/updates qelos.config.json with: {agents: {code-wizard: {json: true, export: "a.md"}}}
qelos agent code-wizard --json --export a.md --save

# Next time, just run — saved defaults apply automatically
qelos agent code-wizard -m "Hello"

The --save flag:

• Creates qelos.config.json if it doesn't exist
• Merges with existing config (preserves other agents and settings)
• Only saves persistent options (e.g. thread, log, export, json, stream) — transient options like --message are not saved

Quick Start

# Install the CLI
npm install -g @qelos/plugins-cli

# Set up a .env file for your instance
echo 'QELOS_URL=https://my-instance.qelos.app' > .env
echo 'QELOS_USERNAME=admin@company.com' >> .env
echo 'QELOS_PASSWORD=secret' >> .env

# Create a new plugin
qplay create my-plugin

# Pull components from your Qelos instance
qelos pull components ./my-components

# Pull blueprints
qelos pull blueprints ./my-blueprints

# Pull configurations
qelos pull config ./my-configs

# Pull integrations & connections
qelos pull integrations ./my-integrations
qelos pull connections ./my-connections

# Generate IDE rules for better AI assistance
qelos generate rules all

# Preview what will be pushed
qelos get staged .
qelos get committed .

# Make changes locally

# Push changes back to Qelos
qelos push components ./my-components
qelos push blueprints ./my-blueprints
qelos push config ./my-configs
qelos push integrations ./my-integrations
qelos push connections ./my-connections

# Push with hard flag to remove remote resources that don't exist locally
qelos push components ./my-components --hard
qelos push all ./my-project --hard

# Push to a different environment using --env
qelos --env production push components ./my-components

# Interact with AI agents
qelos agent code-wizard --message "Hello, how can you help me?"
echo "What's the weather?" | qelos agent weather-agent --stream
qelos agent assistant --log conversation.json --export response.md

# Save agent preferences for reuse
qelos agent code-wizard --stream --log chat.json --save
qelos agent code-wizard -m "Hello"  # uses saved defaults

Commands

Create

Create a new plugin project with all necessary scaffolding and configuration files.

Get

Preview files that would be pushed to your Qelos instance without actually pushing them.

Pull

Pull resources from your Qelos instance to your local filesystem for development.

Push

Push local resources back to your Qelos instance to update or create new items. Use the --hard flag to remove remote resources that don't exist locally.

Generate Rules

Generate IDE-specific rules files to help AI assistants understand your Qelos project structure.

Generate Connection

Create secure connection configuration files for external integrations with interactive setup and environment variable storage.

Agent

Interact with AI agents using the Qelos SDK with support for conversation history, streaming, and response export.

Global Environments

Register a project directory as a named global environment and run agent or data commands from anywhere on your machine using --global.

Use Cases

Local Development

The CLI enables you to:

• Work on components locally with your preferred IDE and tools
• Use version control (Git) for your components
• Collaborate with team members on component development
• Test components locally before deploying to production

Backup and Migration

# Backup all resources from production
qelos pull components ./backups/components-$(date +%Y%m%d)
qelos pull blueprints ./backups/blueprints-$(date +%Y%m%d)
qelos pull config ./backups/configs-$(date +%Y%m%d)

# Preview what will be migrated
qelos get staged ./backups/components-20241109
qelos get staged ./backups/blueprints-20241109

# Migrate to a new instance
export QELOS_URL=https://new-instance.com
qelos push components ./backups/components-20241109
qelos push blueprints ./backups/blueprints-20241109
qelos push config ./backups/configs-20241109

Help

View all available commands and options:

qelos --help
qplay --help

View help for a specific command:

qelos create --help
qelos get --help
qelos pull --help
qelos push --help
qelos generate --help
qelos agent --help
qelos global --help

Troubleshooting

Authentication Issues

If you encounter authentication errors:

1. Verify your environment variables are set correctly
2. Ensure your credentials have the necessary permissions
3. Check that your Qelos instance URL is accessible
4. If using an API token, verify it has not expired or been revoked
5. Use --verbose to see which authentication method is being used

Connection Issues

If the CLI cannot connect to your Qelos instance:

1. Verify the QELOS_URL is correct and accessible
2. Check your network connection
3. Ensure your Qelos instance is running

File Permission Issues

If you encounter file permission errors:

1. Ensure you have write permissions in the target directory
2. Check that the directory path is valid
3. Try using an absolute path instead of a relative path

Related Resources

• Agent Command - Interact with AI agents via command line
• Global Environments - Register projects and run commands from anywhere
• SDK Installation - Install the Qelos SDK for programmatic access
• Plugin Development - Learn how to create plugins
• Components - Learn about Qelos components
• Hard Push Flag - Learn about the --hard flag for synchronizing environments
• Token Usage Tracking - Learn about AI usage tracking