@finalai/cloud

The final-cloud CLI and a client for the Final Cloud public API: create apps, deploy them, and follow deployments and logs.

npm i -D @finalai/cloud
npx final-cloud apps create "My app"

Or run it without installing: npx @finalai/cloud apps create "My app".

Deploying

Each app deploys from its Final repository. apps create prints the repository's remote; push to it, then final-cloud deploy <app> deploys the pushed commit (or --ref).

Environment

• FINAL_API_KEY (required): a Final API key with apps:read and apps:write.
• FINAL_CLOUD_API_HOST: the API origin. The default is https://api.final.ai. Plain http is accepted only for localhost and 127.0.0.1.

Commands

final-cloud apps create <name> [--manifest-path final-cloud.yaml] [--project <prj_...>]
final-cloud deploy <app> [--ref <branch|sha>] [--detach]
final-cloud validate [--manifest final-cloud.yaml]
final-cloud apps list
final-cloud apps get <app>
final-cloud apps delete <app>
final-cloud deployments list <app> [--limit n]
final-cloud deployments get <app> <deployment>
final-cloud rollback <app> <deployment>
final-cloud logs <app> [--deployment id] [--source build|deploy|runtime] [--limit n] [--follow]
final-cloud jobs run <app> <job>
final-cloud types <app> [--out final-cloud.d.ts]
final-cloud schema

<app> is an app id or slug. It must match exactly. --manifest-path is the config's path inside the repository (relative, /-separated); validate reads a local file instead. --project creates the app in another project the key can use; the default is the key's parent project. apps get shows the app's project, and its remote and branch if it has a repository yet.

By default, deploy follows the deployment until it is healthy, failed, or rolled back, then prints the app's URL. With --detach, it prints the deployment id as soon as the deployment starts.

Agents and CI

• --json prints exactly one JSON document on stdout, and progress goes to stderr. logs --follow streams lines, so it cannot be combined with --json.
• --yes answers confirmations. Deploys that widen an app's access (making it public, adding secrets, databases, or domains) need confirmation, and so does apps delete.
• Exit codes:
  • 0: success
  • 1: failure
  • 2: usage or configuration error
  • 3: confirmation required. With --json, stdout is { "confirmationRequired": true, ... } and includes the deploy preview. Re-run with --yes to proceed.

Client

import { createCloudClient, orThrow } from '@finalai/cloud';
const cloud = createCloudClient({
  host: 'https://api.final.ai',
  auth: { apiKey: process.env.FINAL_API_KEY ?? '' },
});
const apps = orThrow(await cloud.apps.list());

Every call returns ResultIface<T> and never throws. Errors are { status, code, message, diagnostics? }, with status 0 when no response arrived. The ./cli entry point exports runCloudCommand with injectable fetch, stdin, prompt, and clock seams.