Publishing

The App SDK ships a publish CLI that uploads a built app bundle to a Hailer instance, and optionally to the Hailer marketplace. Unlike the runtime client, the CLI authenticates directly and needs a user API key or email/password.

What ships, and how to run it

@hailer/app-sdk ships the compiled binary at lib/tools/publish.cjs (built from tools/publish.ts). The npm run publish-* scripts referenced below exist only in projects scaffolded with @hailer/create-app — they are not defined in @hailer/app-sdk itself. In a non-scaffolded project, invoke the binary directly:

node node_modules/@hailer/app-sdk/lib/tools/publish.cjs <bundle>.tgz --user-api-key <key>

The first positional argument is the path to the built .tgz bundle. The CLI exits if it isn't a .tgz file.

# Scaffolded project
npm run publish-production -- --user-api-key <key>

# Create and publish a new app in one run
npm run publish-production -- --create \
  --app-name "My App" \
  --workspace <workspaceId> \
  --user-api-key <key> \
  --force

Authentication

Provide one of:

• --user-api-key <key> — API-key auth. Also read from USER_API_KEY or HAILER_USER_API_KEY.
• --email <email> — email auth; the CLI prompts for the password. Also read from EMAIL.

The USER_API_KEY, HAILER_USER_API_KEY, and EMAIL environment variable forms are slated for deprecation — prefer the flags.

Env-file loading and precedence

The CLI loads env files with dotenv:

1. --env-file <path>, if the file exists, is loaded first.
2. ~/.env is loaded next.

dotenv does not overwrite variables already set, and an earlier-loaded file's values persist over a later one. The effective precedence is:

real environment variables  >  --env-file  >  ~/.env

Target environment

The environment flag selects the default host:

Flag	Host
--production	https://api.hailer.com
--staging	https://api.hailer.biz
--development	https://testapi.hailer.biz
--local	https://api.hailer.local.gd
(none)	https://localhost:9443

--host <url> (or the HOST env var) overrides the host for any mode. --local (or LOCAL) additionally disables TLS certificate verification and, when no API key is given, substitutes local development credentials.

Publishing an existing app

Without --create, the CLI reads the app id from ./dist/manifest.json, verifies the app is accessible with your credentials, and prompts to overwrite before uploading. An app with no workspace (cid) is reported as a personal app.

Creating an app

--create creates the app before publishing. It requires:

• --app-name <name> — the app name (prompted if omitted).
• --workspace <id> — the workspace to create it in (prompted if omitted).

After creating, the CLI writes the new appId back into ./public/manifest.json.

Publishing to the marketplace

--market (or MARKET=true) also publishes the app to the Hailer marketplace. This requires a version (format x.y.z) and versionDescription set in ./public/manifest.json; if they are missing, the CLI writes empty placeholders and exits so you can fill them in.

Flags

Flag	Purpose
--user-api-key <key>	API-key auth.
--email <email>	Email auth (password prompt).
--create	Create a new app before publishing.
--app-name <name>	App name (with --create).
--workspace <id>	Workspace id (with --create).
--market	Also publish to the Hailer marketplace.
--force	Skip the overwrite confirmation. (--yes is the deprecated form.)
--host <url>	Override the target host.
--env-file <path>	Load env vars from a file, in addition to ~/.env.
--development / --staging / --production / --local	Select the default host.

Next steps

• Getting started — build an app before publishing it.
• Reference — the runtime client API.