solidctl Reference

Reference for the SolidX CLI (`solidctl`) used to scaffold, build, upgrade, inspect, seed, test, generate, and run agent tasks in a SolidX project.

CLI Overview

The solidctl CLI is the main command-line entry point for working with SolidX projects.

Mental Model

solidctl is the operational control surface for a SolidX project.

Bootstrap commands create and build the project.
Platform commands seed metadata and inspect project state.
Development commands regenerate code and update package versions.
Testing commands prepare isolated test environments and run scenarios.
Agent commands run the SolidX AI agent.

It is not limited to scaffolding. It is the primary CLI used across project creation, platform maintenance, code generation, testing, and upgrade workflows.

Run it from your project root:

solidctl <command>

For help:

# Top-level help
solidctl --help

# Command-specific help
solidctl <command> --help

Info

This page intentionally documents the most commonly used commands and skips a few internal or less commonly needed ones. In particular, it does not document mcp, legacy-migrate, local-upgrade, or release.

Quick Reference

Command	Description
`create-app`	Scaffold a new SolidX project.
`build`	Build the project and set up the Solid CLI.
`upgrade`	Upgrade SolidX package dependencies.
`seed`	Install or refresh seeded metadata and platform settings.
`info`	Print information about the current project.
`test`	Seed test data or run metadata-driven testing scenarios.
`generate`	Generate backend code boilerplate from metadata.
`agent`	Start the SolidX AI agent server or run a single task.

Command Families

It can help to group the commands mentally before reading the detailed reference:

Bootstrap: create-app, build
Platform lifecycle: seed, info
Development workflow: generate, upgrade
Testing workflow: test
AI workflow: agent

Typical Workflow

First-time setup

# Scaffold a new project
solidctl create-app

# Build the project
solidctl build

# Seed metadata, settings, and the system user
solidctl seed

Day-to-day development

# Regenerate code from metadata
solidctl generate module

# Build after upgrades or major changes
solidctl build

# Inspect project information
solidctl info --detailed

Testing workflow

# Set up test datasource files and databases
solidctl test data --setup

# Seed test data
solidctl test data --load

# Run module scenarios
solidctl test run --module Fees

create-app

Scaffolds a new SolidX project with:

solid-api for the backend
solid-ui for the frontend

By default, create-app runs interactively. Use --no-interactive to skip prompts and rely on flags/defaults instead.

solidctl create-app [options]

Options

Flag	Default	Description
`--verbose`	-	Show detailed logs during installation
`--no-interactive`	-	Skip all prompts and use defaults or provided flags
`--name <name>`	`my-solid-app`	Project name
`--api-port <port>`	`3000`	Backend API port
`--db-client <client>`	`PostgreSQL`	Database type: `PostgreSQL` or `MSSQL`
`--db-host <host>`	`localhost`	Database host
`--db-port <port>`	`5432` / `1433`	Database port
`--db-name <name>`	`solidx_app_db`	Database name
`--db-username <username>`	`solidx_app_user`	Database username
`--db-password <password>`	`strongpassword`	Database password
`--db-synchronize <yes\|no>`	`Yes`	Auto-sync DB schema
`--ui-port <port>`	`3001`	Frontend port

What it does

Creates a new project directory.
Scaffolds solid-api and solid-ui.
Installs dependencies.
Writes environment configuration.
Prints the next commands to run.

Recommended next steps

solidctl build
solidctl seed

build

Builds SolidX and sets up the Solid CLI.

solidctl build [options]

Options

Flag	Description
`--ui-only`	Build only `solid-ui` and skip the `solid-api` build

Notes

Run this after scaffolding a new project.
Run this again after upgrades.
Run this if CLI-backed commands are not seeing your latest local code.

upgrade

Upgrades SolidX dependencies. By default, this upgrades to the latest beta pre-release.

solidctl upgrade [options]

Options

Flag	Description
`--core`	Upgrade `solid-core` only
`--ui`	Upgrade `solid-ui` only
`--code-builder`	Upgrade `solid-code-builder` only
`--dry-run`	Show commands without executing
`--stable`	Upgrade to the latest stable release instead of beta
`--tag <tag>`	Install a specific pre-release tag such as `alpha` or `rc`

Examples

# Upgrade everything to latest beta
solidctl upgrade

# Upgrade only solid-core
solidctl upgrade --core

# Upgrade only solid-ui
solidctl upgrade --ui

# Upgrade only solid-code-builder
solidctl upgrade --code-builder

# Upgrade to latest stable
solidctl upgrade --stable

# Upgrade to a specific pre-release track
solidctl upgrade --tag alpha

# Preview without changing anything
solidctl upgrade --dry-run

Recommended follow-up

After upgrading, run:

solidctl build

seed

Seeds metadata and platform-level data into the application.

solidctl seed [options]

Options

Flag	Default	Description
`-m, --modules-to-seed [module names]`	all modules	Comma-separated list of module names to seed
`-s, --seeder [seeder name]`	`ModuleMetadataSeederService`	Seeder to run
`--prune`	-	Remove metadata that is no longer present in JSON

When to use it

After initial project setup
After changing metadata JSON files
After upgrades that introduce new platform metadata

Examples

# Seed everything
solidctl seed

# Seed only selected modules
solidctl seed --modules-to-seed Fees,Onboarding

# Seed and prune removed metadata
solidctl seed --prune

info

Prints information about the consuming project.

solidctl info [options]

Options

Flag	Description
`-d, --detailed`	Print more details about the consuming project

Use this when debugging project configuration, versions, or runtime setup.

test

The test command has two main areas:

test data for test data and datasource lifecycle tasks
test run for scenario execution

For the broader testing architecture, vocabulary, and workflow, see Testing.

solidctl test [command]

test data

Seeds test data from metadata or manages test datasource setup and teardown.

solidctl test data [options]

Options

Flag	Description
`--load`	Seed test data from `testing.data` sections
`--setup`	Create a new `.env.<dbRunName>` and test datasource manifest
`--teardown`	Delete the test datasource env/manifest and drop test databases
`--modules-to-test [module names]`	Comma-separated list of module names to test; defaults to all modules

Examples

# Set up test environment
solidctl test data --setup

# Load all test data
solidctl test data --load

# Load only selected modules
solidctl test data --load --modules-to-test Fees,Onboarding

# Tear down test environment
solidctl test data --teardown

test run

Runs testing scenarios from module metadata.

solidctl test run [options]

Options

Flag	Description
`-m, --module [module name]`	Module name to load metadata from
`--scenario-ids [ids]`	Comma-separated list of scenario ids to run
`--include-tags [tags]`	Comma-separated list of tags; scenario must include all
`--skip-scenario-ids [ids]`	Comma-separated list of scenario ids to skip
`--reporter [name]`	Reporter name; currently `console`
`--list-specs [true\|false]`	List registered test specs and exit
`--print-api-logs [true\|false]`	Print full API request/response logs for `api.request` steps
`--api-base-url [url]`	API base URL; defaults to `process.env.BASE_URL`
`--ui-base-url [url]`	UI base URL; defaults to `process.env.FRONTEND_BASE_URL`
`--headless [true\|false]`	Run UI browser in headless mode; default `true`
`--timeout-ms [number]`	Default scenario timeout in milliseconds
`--retries [number]`	Default scenario retries

Examples

# Run all scenarios for a module
solidctl test run --module Fees

# Run specific scenarios
solidctl test run --module Fees --scenario-ids sc-001,sc-002

# Run tagged scenarios only
solidctl test run --module Fees --include-tags smoke

# Run with visible browser and verbose API logs
solidctl test run --module Fees --headless false --print-api-logs true

# List registered specs
solidctl test run --module Fees --list-specs true

generate

Generates code boilerplate from model metadata configurations.

solidctl generate [command]

Subcommands

Subcommand	Description
`model`	Generate code for a single model and its related models
`module`	Generate code for an entire module; this is the recommended path

Guidance

Prefer generate module for most workflows.
Use generate model when you want a smaller, targeted refresh.
This command is about metadata-driven code generation, primarily for generated backend structure.

For a deeper explanation of generated structure and the surrounding conventions, see Code Generation.

agent

Runs the SolidX AI agent.

solidctl agent [command]

Subcommands

Subcommand	Description
`start`	Start the AI agent server
`run <task>`	Run a single agent task

Examples

# Show help for the agent command
solidctl agent --help

# Show help for starting the agent server
solidctl agent start --help

# Run a single task
solidctl agent run "summarise project metadata"

solidctl Reference

On this page