Getting Started - Overlayed

Installation

pnpm i @overlayed/cli -g

npm i @overlayed/cli -g

yarn add @overlayed/cli -g

Usage

overlayed <command>

Authentication

You can authenticate in two ways:

Interactive login - Run overlayed login to authenticate via browser
Environment variable - Set OVERLAYED_API_KEY for CI/CD or programmatic use

The environment variable takes precedence over stored credentials when both are present.

Update Checks

Every command checks npm for a newer @overlayed/cli, and overlayed bundle also checks the @overlayed/app and @overlayed/electron versions installed in your project. If any are out of date, a warning is printed to stderr before the command runs. The check never fails a command: if the registry can’t be reached or doesn’t answer within 1.5 seconds, it is skipped silently. Snapshot installs (e.g. @canary) are not checked.

Commands

Authenticate with the Overlayed platform. This is required for local development. Opens the dashboard’s API key creation page with the key name prefilled as cli and the asset bundle read and write permissions preselected, so the resulting key can run overlayed bundle without further setup. The permissions are only a starting point — add or remove any of them before creating the key.

`overlayed logout`

Log out of the currently authenticated account.

`overlayed whoami`

Display information about the currently authenticated user.

`overlayed init`

Initialize your local development environment. This command:

Fetches your application metadata from the Overlayed API
Creates a .overlayed/meta.json file with cached application data
Must be run after overlayed login and in a directory with an overlayed.config.ts file

This only needs to be run once per project.

`overlayed bundle`

Bundles the app and site for deployment. This command looks for an overlayed.config.ts file in the current directory and bundles the app and site for deployment. Options:

Flag	Description
`--app [name]`	Bundle the app. Optionally provide a custom name (random if omitted).
`--site [name]`	Bundle the site. Optionally provide a custom name (random if omitted).
`--debug`	Enable debug mode. Outputs bundled file paths and saves zips to `.overlayed/tmp/` instead of uploading.
`--debug-files`	List the files that would be included in each bundle, then exit. No authentication or upload occurs.
`--no-wait`	Skip waiting for bundle processing to complete.

Each uploaded bundle prints a link to its own build job in the dashboard, where you can follow its progress. Examples:

# Interactive - select bundles and enter names via prompts
overlayed bundle

# Bundle app with a specific name
overlayed bundle --app my-app-v1

# Bundle both with custom names
overlayed bundle --app my-app --site my-site

# Bundle app with random name (skip name prompt)
overlayed bundle --app

# Bundle and skip waiting for processing
overlayed bundle --no-wait

# Preview which files each bundle would include, then exit
overlayed bundle --debug-files

Read more about deploying your overlay here.

Programmatic API

The CLI package exports functions for programmatic use. They have the same options and functionality as the CLI commands.

import { bundle } from "@overlayed/cli";

// Bundle with options
await bundle({ debug: true });

This is useful for custom build scripts or tooling integration.

​Installation

​Usage

​Authentication

​Update Checks

​Commands

​overlayed login

​overlayed logout

​overlayed whoami

​overlayed init

​overlayed bundle

​Programmatic API