Installation

Prerequisites

Before installing the Apso CLI, ensure the following tools are available on your machine:

Verify your versions:

node --version   # v18.x.x or higher
npm --version    # 8.x.x or higher
git --version    # any version

Install Globally via npm

The recommended way to install the CLI is as a global npm package:

npm install -g @apso/cli

After installation, the apso command is available system-wide:

apso --version
# @apso/cli/0.8.3

Use Without Installing (npx)

If you prefer not to install the CLI globally, you can run it on-demand with npx:

npx @apso/cli server new --name my-api
npx @apso/cli server scaffold --language typescript

This downloads and runs the latest version each time. It is useful for one-off operations or CI pipelines where you want to avoid global installs.

Note: The Apso platform’s in-browser editor uses npx --yes @apso/cli to run scaffold operations inside a WebContainer. The --yes flag auto-confirms the install prompt.

Install as a Project Dependency

You can also add the CLI as a dev dependency in an existing project:

npm install --save-dev @apso/cli

Then reference it in your package.json scripts:

{
  "scripts": {
    "scaffold": "apso server scaffold --language typescript",
    "scaffold:python": "apso server scaffold --language python",
    "scaffold:go": "apso server scaffold --language go"
  }
}

Run with:

npm run scaffold

Updating the CLI

To update a global installation to the latest version:

npm update -g @apso/cli

To check which version you have installed:

apso --version

Local Development (Contributing)

If you are working on the CLI itself, clone the repository and link it locally:

git clone https://github.com/apsoai/cli.git
cd cli
npm install
npm run build && npm link

This builds the CLI from source and makes it available as the global apso command. After making changes, rebuild before testing:

npm run build

To run the CLI with debug output enabled:

env DEBUG=* apso server scaffold

Troubleshooting

Permission Errors on Global Install

If npm install -g fails with EACCES permission errors:

# Option 1: Configure npm to use a user-writable directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Add the export line to your shell profile (~/.bashrc, ~/.zshrc, etc.)
 
# Option 2: Use npx instead of a global install
npx @apso/cli server new --name my-api

Node.js Version Too Old

The CLI requires Node.js 18 or higher. If your system has an older version, use nvm  to manage multiple versions:

nvm install 18
nvm use 18
node --version  # v18.x.x

Git Not Found

The apso server new command requires Git to clone the project template. If you see git is required but not found, install Git for your platform:

• macOS: xcode-select --install or brew install git
• Linux: sudo apt install git (Debian/Ubuntu) or sudo yum install git (RHEL/CentOS)
• Windows: Download from git-scm.com 

SSH Key Issues When Cloning Templates

If the template clone fails with a permission error, ensure your GitHub SSH key is configured. Follow the GitHub SSH key guide  to generate and add a key.

The CLI clones templates over HTTPS by default, so SSH issues are uncommon. If you encounter them, verify the template repository URLs are accessible:

• TypeScript: https://github.com/apsoai/service-template.git
• Python: https://github.com/apsoai/service-template-python.git
• Go: https://github.com/apsoai/service-template-go.git

Next Steps

• Create a new project with apso server new
• Generate code with apso server scaffold
• Configure your .apsorc schema