Skip to content
SolidXAIPublic

About

The developer CLI for the SolidX platform - scaffold, build, seed, generate, and release your SolidX application from a single tool.

Resources

Stars

16 stars

Watchers

0 watching

Forks

Repository files navigation

solidctl

The developer CLI for the SolidX platform — scaffold, build, seed, generate, and release your SolidX application from a single tool.

solidctl is the command-line interface that ties the SolidX ecosystem together. Whether you are starting a new project, upgrading core dependencies, or regenerating code after a model change using the command line, solidctl is the entry point.

npm version License: BSL-1.1 Documentation Discord


Usage

The recommended way to run solidctl is via npx, which ensures you are always using the latest version without needing a global install:

solidctl <command>

All examples in this README use npx. If you prefer a global install:

npm install -g @solidxai/solidctl
solidctl <command>

However please note that a global install may become outdated, so we recommend using npx for the best experience.


Quick start

Scaffold a new SolidX project with a single command:

solidctl create-app

The interactive wizard will ask for your project name, database connection details, and port configuration, then scaffold a complete project structure:

my-solid-app/
├── solid-api/    # NestJS backend powered by @solidxai/core
└── solid-ui/     # React frontend powered by @solidxai/core-ui

Once created, build the API and bootstrap the database:

cd my-solid-app
solidctl build   # compiles solid-api and sets up the local solid CLI
solidctl seed    # seeds the database with SolidX metadata and system defaults

Commands

create-app

Scaffolds a new SolidX project. Runs an interactive setup wizard by default; all options can also be passed as flags for non-interactive use.

solidctl create-app [options]
Flag Default Description
--name <name> my-solid-app Project directory name
--api-port <port> 3000 Port for the NestJS API
--ui-port <port> 3001 Port for the React frontend
--db-client <client> postgres Database client (postgres, mysql, etc.)
--db-host <host> localhost Database host
--db-port <port> 5432 Database port
--db-name <name> solidx_app_db Database name
--db-username <user> solidx_app_user Database username
--db-password <pass> strongpassword Database password
--db-synchronize false Enable TypeORM schema auto-sync
--no-interactive — Skip prompts and use flag values / defaults

setup-app

Sets up an already-bootstrapped SolidX project you've just cloned — the counterpart to create-app for a project that already exists. Infers what it can from the repo (project name, UI port), prompts only for the database connection, then installs, configures, builds, seeds, and starts the project.

solidctl setup-app [options]
Flag Description
--no-start Skip starting the dev servers after setup
--no-interactive Skip all prompts and use defaults (or provided flags)
--verbose Show detailed logs during installation
--skip-install Skip npm install for solid-api and solid-ui
--skip-build Skip the build step
--skip-seed Skip the seed step
--force-env Regenerate .env files even if they already exist
--db-client <client> PostgreSQL, MySQL, or MSSQL
--db-host <host> Database host
--db-port <port> Database port
--db-name <name> Database name
--db-username <username> Database username
--db-password <password> Database password

If solid-api/.env already exists, it's left untouched (pass --force-env to regenerate). If a solid-api/.env.example exists, its non-secret values are carried over and only the gaps (and the database password) are prompted for. Otherwise, only the database connection is prompted for — other project-specific settings (RabbitMQ, OAuth, SMTP, Redis, etc., if the project uses them) aren't known ahead of time and need to be added manually afterward.

Requires both solid-api/package.json and solid-ui/package.json to define a solidx:dev script. If either is missing (a project that predates that script), setup fails fast and tells you the exact line to add.


build

Builds the NestJS API and sets up the local solid CLI shim so subsequent solidctl commands that proxy into the API (like seed, generate, and test) work correctly. Run this after project creation and after any changes to solid-api.

solidctl build

This command:

  1. Runs npm run build inside solid-api/
  2. Creates a local solid CLI shim that points to the compiled output
  3. Verifies the shim is working correctly

Must be run from the project root (the directory containing both solid-api/ and solid-ui/).


seed

Seeds the database with SolidX system metadata, permissions, default settings, and the initial admin user. Run once after the database is created and after any module metadata changes.

solidctl seed

Proxies to the solid seed command inside solid-api/. Any additional arguments are passed through. Use solidctl seed --verbose to show detailed Nest/Winston logs during seeding.


generate

Regenerates NestJS boilerplate (entity, service, controller, repository, DTOs) for a model or an entire module based on the current metadata. Safe to run repeatedly — existing custom logic in generated files is preserved.

# Regenerate a single model and its related models
solidctl generate model <model-name>

# Regenerate all models within a module
solidctl generate module <module-name>

Under the hood, this proxies to solid refresh-model / solid refresh-module, which invokes @solidxai/code-builder to perform AST-level file updates.


migration

Runs the TypeORM migration workflow for a chosen datasource, while keeping migration files organized under the module-specific datasource folder.

# Generate a migration file into src/<module>/migrations/<datasource>/
solidctl migration -d applications -m onboarding generate Added_PreApplication_Master

# Run all pending migrations for a datasource
solidctl migration -d applications run

# Revert the last migration for a datasource
solidctl migration -d applications revert

This command validates the datasource file, validates the module’s entities folder for generate, and then runs typeorm-ts-node-commonjs inside solid-api/.


upgrade

Upgrades the core SolidX dependencies in both solid-api and solid-ui to the latest available version.

# Upgrade to the latest beta pre-release (default)
solidctl upgrade

# Upgrade to the latest alpha pre-release
solidctl upgrade --alpha

# Upgrade to the latest stable release
solidctl upgrade --stable

# Upgrade to a specific dist-tag
solidctl upgrade --tag next

# Preview what would change without installing
solidctl upgrade --dry-run

Packages upgraded:

  • solid-api: @solidxai/core, @solidxai/code-builder
  • solid-ui: @solidxai/core-ui

test

Runs the SolidX metadata-driven test suite defined in your module metadata. Proxies to solid test inside solid-api/.

solidctl test [args]

All arguments are passed through to the underlying solid test command. See the testing framework documentation for details on writing test scenarios.


info

Prints information about the current SolidX project — versions, configuration, and environment. Useful for debugging and support.

solidctl info

start:dev

Starts both consuming-project dev servers in one supervised terminal session with merged logs by default.

solidctl start:dev

Enable the interactive control pane and keyboard shortcuts when you want them:

solidctl start:dev --controls

Keyboard shortcuts in interactive terminals with --controls:

  • a restart solid-api
  • u restart solid-ui
  • r restart both
  • c clear the terminal
  • q stop both and quit

This command validates that both solid-api/package.json and solid-ui/package.json define a solidx:dev script before starting either process.


agenthub start

Starts the AgentHub runtime manager from your SolidX project root (default: 127.0.0.1:9001).

# Local checkout; creates/reuses its .venv and installs editable source
export AGENT_HUB_RUNTIME_PATH=/path/to/agent-hub-runtime
solidctl agenthub start --local

# After solidx-agenthub-runtime is published to PyPI
solidctl agenthub start

# Change the manager bind address/port
solidctl agenthub start --local --host 127.0.0.1 --port 9002

# Pass variables directly to the AgentHub manager and its child processes
solidctl agenthub start --env AGENT_HUB_WORKERS=2 --env FEATURE_FLAG=true

--env is repeatable and accepts KEY=VALUE. Command-line values override values loaded from the environment or .env files. The manager and processes it launches inherit these variables.

Python 3.11+ is required. Published installs use a separate ~/.solidx/agenthub-venv; prerelease versions of solidctl allow prerelease packages with --pre. Until the runtime package is published, use --local.

Like solidctl agent start, published mode checks PyPI for updates on solidctl's stable/beta track and asks before upgrading in an interactive terminal (default: no). Non-interactive runs print the manual upgrade command. A successful upgrade exits so you can rerun the command; --local skips the update check.

Settings load from the OS environment, project-root .env, then solid-api/.env (earlier values win). DATABASE_URL can be built from DEFAULT_DATABASE_*; SOLIDX_API_BASE_URL is preferred for SolidX API calls, with BASE_URL as a compatibility fallback. Pass APP_ENCRYPTION_KEY for linked secrets and AGENT_HUB_MANAGER_INTERNAL_TOKEN for chat/MCP, along with any other AGENT_HUB_* settings. Ctrl+C stops the manager and its agent processes.


agenthub searxng

Manages the local SearXNG container that backs the AgentHub web_search tool. Docker is required. The commands delegate to agenthub-runtime searxng, so container name, image, port, and settings stay defined in one place.

solidctl agenthub searxng up --local       # create/start agenthub-searxng and wait for /healthz (--wait 0 to skip)
solidctl agenthub searxng status --local   # state, image, URL, health; exits non-zero when not healthy
solidctl agenthub searxng logs --local --tail 200
solidctl agenthub searxng down --local     # remove the container; ~/.agenthub/searxng/settings.yml is kept

# Use a different host port (match it when starting the manager)
solidctl agenthub searxng up --local --env AGENT_HUB_SEARXNG_PORT=8899

# Start SearXNG automatically with the manager instead
solidctl agenthub start --local --env AGENT_HUB_SEARXNG_AUTOSTART=1

Every subcommand accepts --local and repeatable --env KEY=VALUE, like agenthub start. SearXNG is machine-wide, so these commands do not require a project root, but they read .env and solid-api/.env from the current directory when present so AGENT_HUB_SEARXNG_* settings match the manager. They skip the PyPI update check. If the installed runtime predates the SearXNG commands, solidctl tells you to upgrade or use --local.


Project structure

A project created by solidctl create-app follows this layout:

my-solid-app/
├── solid-api/                  # NestJS backend
│   ├── src/
│   │   ├── app.module.ts       # Root module importing SolidCoreModule
│   │   ├── main.ts             # Application entry point
│   │   └── {your-modules}/     # Generated modules live here
│   │       └── metadata/       # Metadata JSON files driving code generation
│   └── package.json
│
└── solid-ui/                   # React frontend
    ├── src/
    │   ├── main.tsx            # App entry point
    │   └── App.tsx             # Root component with SolidX providers
    └── package.json

Part of the SolidX Platform

solidctl is the developer interface to the full SolidX package ecosystem:

Package Role
@solidxai/core NestJS backend module — auth, CRUD, IAM, notifications, queues
@solidxai/core-ui React admin panel — metadata-driven views, auth UI, Redux store
@solidxai/code-builder Code generation engine — produces NestJS files from metadata
@solidxai/solidctl This CLI — scaffolds, builds, generates, and upgrades
Website solidxai.com
Documentation docs.solidxai.com
Discord discord.gg/ATQW4CEksA
Support support@solidxai.com

License

BSL-1.1 © Logicloop

About

The developer CLI for the SolidX platform - scaffold, build, seed, generate, and release your SolidX application from a single tool.

Resources

Stars

16 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages