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.
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.
Scaffold a new SolidX project with a single command:
solidctl create-appThe 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 defaultsScaffolds 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 |
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.jsonandsolid-ui/package.jsonto define asolidx:devscript. If either is missing (a project that predates that script), setup fails fast and tells you the exact line to add.
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 buildThis command:
- Runs
npm run buildinsidesolid-api/ - Creates a local
solidCLI shim that points to the compiled output - Verifies the shim is working correctly
Must be run from the project root (the directory containing both
solid-api/andsolid-ui/).
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 seedProxies 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.
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.
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 revertThis command validates the datasource file, validates the module’s entities folder for generate, and then runs typeorm-ts-node-commonjs inside solid-api/.
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-runPackages upgraded:
solid-api:@solidxai/core,@solidxai/code-buildersolid-ui:@solidxai/core-ui
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.
Prints information about the current SolidX project — versions, configuration, and environment. Useful for debugging and support.
solidctl infoStarts both consuming-project dev servers in one supervised terminal session with merged logs by default.
solidctl start:devEnable the interactive control pane and keyboard shortcuts when you want them:
solidctl start:dev --controlsKeyboard shortcuts in interactive terminals with --controls:
arestartsolid-apiurestartsolid-uirrestart bothcclear the terminalqstop 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.
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.
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=1Every 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.
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
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 |
BSL-1.1 © Logicloop