Apso CLI
Define a schema. Get a production API. Keep the code.
Apso generates production-ready backend services from a JSON schema file. You get real framework code (NestJS, FastAPI, or Gin) that you own, run anywhere, and extend with standard patterns. For the complete documentation, see Apso Docs.
Install
Homebrew (macOS / Linux)
brew install apsoai/tap/apso
# Installed before Homebrew 6? Trust the formula so upgrades work:
# brew trust --formula apsoai/tap/apso
npm
npm install -g @apso/cli
Requires Node.js 18.0 or higher.
MCP Server (AI editor integration)
Apso works as an MCP server inside Claude Code, Cursor, Windsurf, and other MCP-compatible editors. Your AI assistant can design schemas, generate APIs, and deploy backends through conversation.
Claude Code
claude mcp add apso -- apso mcp serve
Cursor / VS Code / Other editors
Add to your MCP configuration:
{
"mcpServers": {
"apso": {
"command": "apso",
"args": ["mcp", "serve"]
}
}
}
Available tools:
| Tool | Description |
|---|---|
design_schema | Design a database schema from application requirements |
validate_schema | Validate an .apsorc schema file |
scaffold_api | Generate API code from schema (TypeScript, Python, or Go) |
setup_auth | Configure authentication (BetterAuth, Auth0, Clerk, Cognito, API Keys) |
start_dev_server | Start local dev environment via Docker Compose |
deploy_api | Deploy to the Apso platform |
Schema edit tools (from @apso/schema-tools) change the project's .apsorc one step at a time. Each write is linted with the rules apso generate enforces; a change that would add a lint error is rejected and the file is left as it was.
| Tool | Description |
|---|---|
get_schema, describe_entity | Read the schema outline, or one entity and its relationships |
add_entity, rename_entity, remove_entity | Entities (relationships and foreign key indexes follow renames and removals) |
add_field, update_field, rename_field, remove_field | Fields (indexes and uniques follow renames and removals) |
add_relationship, remove_relationship | Relationships |
add_index | Index or unique index |
lint_schema | Lint report |
Available resources:
| Resource | URI | Description |
|---|---|---|
| Schema reference | apso://schema-guide | Schema design guidelines and examples |
| Current schema | apso://current-schema | Your project's current .apsorc |
Connect
Authenticate with the Apso platform:
apso login
This opens a browser window for OAuth authentication. For CI/CD environments, use a token:
apso login --token <api-token>
Quick start
# Create a new project
apso init --name my-app --language typescript
# Edit .apsorc to define your schema
# Generate code from schema
apso generate
# Start Postgres and run the API
apso dev
Your API is live at http://localhost:3000 with Swagger docs at /api. The generated code lives in src/autogen/ and is standard NestJS with TypeORM -- no Apso runtime dependency.
Commands
| Command | Subcommands | Description |
|---|---|---|
| init | Create a new project | |
| generate | Generate code from .apsorc schema | |
| dev | Start local dev server via Docker Compose | |
| migrate | Test schema migrations locally with PGlite | |
| deploy | Deploy to Apso platform | |
| login | Authenticate with Apso | |
| logout | Clear stored credentials | |
| whoami | Show current user | |
| link | Link project to a platform service | |
| unlink | Remove platform link | |
| status | Show service and build status | |
| logs | View build logs | |
| open | Open service dashboard in browser | |
| projects | List services in a workspace | |
| config | get, set, reset | View or modify CLI configuration |
| schema | diff, push, pull, validate | Manage schema sync with platform |
| mcp serve | Start MCP server for AI editors |
Command reference
apso init
Create a new Apso project from a language-specific template.
apso init
apso init --name my-app --language typescript
apso init --name my-app --language python --skip-platform
| Option | Description | Default |
|---|---|---|
-n, --name | Project name | (prompted) |
-l, --language | Target language (typescript, python, go) | (prompted) |
--skip-platform | Skip platform linking (offline mode) | false |
When authenticated, apso init lets you create a new project or clone an existing one from the platform.
apso generate
Generate backend code from the .apsorc schema file.
apso generate
apso generate --language python
apso generate --skip-format
| Option | Description | Default |
|---|---|---|
-l, --language | Target language (typescript, python, go) | (from .apsorc or prompted) |
--skip-format | Skip Prettier formatting after generation | false |
Generated files are placed in src/autogen/. These files are overwritten on each run. Place custom code in src/extensions/ to avoid losing changes.
apso dev
Start the local development server using Docker Compose.
apso dev
apso dev --build
apso dev --detach
| Option | Description | Default |
|---|---|---|
--build | Rebuild images before starting | false |
-d, --detach | Run containers in the background | false |
Requires Docker and Docker Compose. Looks for docker-compose.yml in the current directory.
apso migrate
Write the migration for a schema change without losing data. apso migrate regenerates the code, compares .apsorc with the deployed schema, and asks about every change whose intent the schema can't show: was a missing field renamed or dropped, how does a field split, what replaces a removed enum value, what do existing rows get for a new required field. It then writes the migration from your answers (a TypeORM migration for TypeScript, an Alembic revision for Python, a goose file for Go), saves the answered plan beside it, and tests it on a local PGlite copy of the deployed schema.
apso migrate --baseline deployed.apsorc # first time: the .apsorc that is deployed
apso migrate # later runs find the baseline from the last migration
apso migrate --answer field:Contact.phone=rename:mobilePhone
apso migrate --seed seed.sql --check checks.sql
In a terminal it asks each question. Without one (or with --json) it prints the open questions as JSON and exits 2, so a coding agent can answer them with --answer or in .apso/migration-plan.json and run it again. The same answers always produce the same SQL.
The steps are also separate commands: apso migrate plan, apso migrate generate and apso migrate verify. apso migrate sandbox is the older snapshot preview on an empty database (--apply, --reset, --sql).
apso deploy
Deploy the linked service to the Apso platform. Runs a local migration check before deploying.
apso deploy
apso deploy --yes
apso deploy --skip-migrate
apso deploy --no-wait
| Option | Description | Default |
|---|---|---|
-y, --yes | Skip confirmation prompt | false |
--skip-migrate | Skip local migration validation | false |
--no-wait | Trigger deploy without waiting for completion | false |
If schema changes are detected, apso deploy shows the migration SQL and asks for confirmation before proceeding. If the migration fails locally, the deploy is blocked.
apso login
Authenticate with the Apso platform via browser-based OAuth or API token.
apso login
apso login --token <api-token>
| Option | Description |
|---|---|
-t, --token | API token for non-interactive login (CI/CD) |
apso logout
Clear stored credentials.
apso logout
apso whoami
Display information about the current authenticated user and linked project.
apso whoami
apso link
Link the current project to a platform service.
apso link
apso link --workspace my-team --service my-api
apso link --force
| Option | Description |
|---|---|
-w, --workspace | Workspace slug |
-s, --service | Service slug |
-f, --force | Overwrite existing link without confirmation |
apso unlink
Remove the link between the current project and the platform.
apso unlink
apso status
Show the current service and latest build status.
apso status
apso logs
View build logs for the linked service.
apso logs
apso logs <build-id>
apso open
Open the service dashboard or API endpoint in the browser.
apso open
apso projects
List services in a workspace.
apso projects
apso config
View or modify CLI configuration.
apso config # Show all settings
apso config get apiUrl # Get a specific value
apso config set verbose true # Set a value
apso config reset # Reset to defaults
Configuration keys:
| Key | Type | Description |
|---|---|---|
apiUrl | string | Platform API URL |
webUrl | string | Platform web URL |
verbose | boolean | Enable verbose output |
noColor | boolean | Disable colored output |
telemetryDisabled | boolean | Opt out of anonymous telemetry (or apso config set telemetry off) |
defaultWorkspace | string | Default workspace slug |
Boolean values accept true/false or 1/0.
Environment variables override config file values:
| Variable | Overrides |
|---|---|
APSO_API_URL | apiUrl |
APSO_WEB_URL | webUrl |
APSO_DEBUG=true | verbose |
NO_COLOR or APSO_NO_COLOR=true | noColor |
APSO_TELEMETRY=0 / DO_NOT_TRACK=1 | telemetryDisabled |
apso schema
Manage schema synchronization between local .apsorc and the platform.
apso schema validate # Validate local schema
apso schema diff # Show diff between local and remote
apso schema push # Push local schema to platform
apso schema pull # Pull remote schema to local
Global options
These options work with any command:
apso [command] --help # Show command help
apso [command] --version # Show CLI version
Telemetry & privacy
The CLI sends anonymous usage data so we can see which commands are used and prioritize accordingly. It is opt-out and carries no personal data.
What is collected: command name (generate, init, deploy, …), CLI
version, OS and architecture, Node version, command duration and success, and
an anonymous install id (a random UUID stored in your CLI config — not derived
from any machine identifier). If you are logged in, events attribute to your
Apso account, the same as the web app.
What is never collected: your source code, your .apsorc or schema
contents, file paths, environment variable values, or any other file contents.
Opt out any of these ways:
apso config set telemetry off # persisted in your CLI config
export APSO_TELEMETRY=0 # per-shell
export DO_NOT_TRACK=1 # honors the consoledonottrack.com standard
On first run the CLI prints a one-time notice pointing at these opt-outs.
See docs/telemetry.md for full detail. Aggregate
public download stats (npm/PyPI) are available via node scripts/usage-stats.mjs.
Supported languages
| Language | Framework | ORM | Status |
|---|---|---|---|
| TypeScript | NestJS | TypeORM | Stable |
| Python | FastAPI | SQLAlchemy | In development |
| Go | Gin | GORM | In development |
Contribute
git clone https://github.com/apsoai/cli.git
cd cli
npm install
npm run build
To run commands from the local build:
./bin/run generate
./bin/run migrate --sql
To develop continuously:
npm run build # Rebuild after changes
npm link # Make 'apso' command available globally
Testing
npm run test # Run all tests
npm run test:watch # Watch mode
npm run test:cov # Coverage report
Debugging
env DEBUG=* ./bin/run generate
License
MIT