@northslopetech/ns-cli

CLI tool for bootstrapping OSDK apps with Northslope best practices.

Usage

# Scaffold a new project
ns osdk create

# Configure GitHub Actions and production hosting
ns osdk setup-deployment

Running ns osdk setup-deployment configures the GitHub repository with:

• Environment variables required for builds (VITE_FOUNDRY_*)
• The staging domain origin as WEBSITE_BASE_URL, used by the PR preview workflow
• FOUNDRY_TOKEN as a repository secret for deployments

GitHub Actions

Generated projects include two workflows:

• Publish Frontend to Foundry publishes tagged releases to production.
• Deploy PR Preview builds pull requests and deploys upload-only previews, posting a link based on WEBSITE_BASE_URL/.system/preview?previewVersion=<version>. It skips automatically until you run ns osdk setup-deployment to configure the required repository variables and secrets.

Requirements

• Node.js >= 18
• A Foundry account with Developer Console access

Configuration

The CLI stores Foundry credentials (tokens and stack URLs) in a user-level config file at ~/.northslope/ns.config.json.

To use a different location — useful in CI or when running multiple isolated environments — set the NS_HOME_CONFIG_PATH environment variable to the desired file path:

NS_HOME_CONFIG_PATH=/tmp/my-ns-config.json ns osdk get-token

All read and write operations (token storage, stack URL, impl listing) will use the path you specify instead of the default.

Development

Getting started (dev)

pnpm install
pnpm run dev -- create

Build & try as a package

pnpm run build && pnpm link
ns osdk create

Run tests & linting / formatting

pnpm run test
pnpm run lint
pnpm run format