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 tap apsoai/tap
brew install 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

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

Detect schema changes, generate migration SQL, and test against a local PGlite sandbox. No Docker or external database required.

apso migrate              # Detect changes, generate and test SQL
apso migrate --apply      # Update snapshot after successful test
apso migrate --reset      # Clear sandbox and start fresh
apso migrate --sql        # Output raw SQL only (for piping)

Option	Description	Default
--apply	Update local schema snapshot after verified migration	false
--reset	Reset the sandbox (clear snapshot and PGlite data)	false
--sql	Output raw SQL statements only	false

The sandbox works by comparing your current .apsorc against the last-known snapshot, generating the migration SQL, and executing it against an in-process Postgres instance (PGlite). If the migration fails locally, you know before it reaches any real database.

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
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 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

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