CLI configuration

Common optionsCopy Anchor Link

Options you can add to any ntro command.

You rarely need --api or --identity. If you do, the first value found wins: flag → environment variable (NITROSHIP_API_URL, NITROSHIP_IDENTITY_URL) → saved value → default.

Interactive mode and automationCopy Anchor Link

ntro asks for missing arguments and double-checks actions such as deleting or promoting. These prompts appear only when all of the following hold:

• Both stdin and stderr are terminals.
• --json is not set.
• The CI environment variable is not set. (Even an empty value counts as set, meaning automation.)

Automation cannot answer prompts, so:

• Provide every required argument, such as app, team, and deployment IDs, and member emails and roles.
• Add --yes to actions that need confirmation (delete, cancel, promote, roll back, and so on).
• Add --app <app> when deploying a folder that is not linked.

AuthenticationCopy Anchor Link

The CLI uses the first credential it finds, in this order:

1. The --token flag
2. The NITROSHIP_TOKEN environment variable
3. The login saved by ntro login

• For people: log in with ntro login. See Log in.
• For automation: pass an ntro_ API token in NITROSHIP_TOKEN. See API tokens.
• Log out: ntro logout invalidates the saved login on the server and removes it from local files.

Either way, the CLI sends a five-minute access token with API requests and renews it automatically when it expires.

Files stored locallyCopy Anchor Link

Set NITROSHIP_CONFIG_DIR to use another folder instead of ~/.nitroship.

App linksCopy Anchor Link

Link a folder to an app and commands run in that folder no longer need --app. The link stores the app ID, so changing the app's slug never requires relinking.

ntro apps create my-app   # create an app and link the current folder
ntro link my-app          # link the current folder to an existing app (or switch)
ntro unlink               # remove the current folder's link

• apps create links the current folder by default. Add --no-link to skip it; --json also skips it.
• Run ntro link without an argument to pick from your apps. Automation must name the app.
• ntro unlink only deletes .nitroship/app.json (and the older .nitroship/project.json). It never deletes the app, needs no login, and succeeds even with no link.
• Relink if you switch to an app in another team or the linked app moves to a different team.

Build frameworkCopy Anchor Link

Set build.framework in nitroship.json at the deployment root to choose a managed framework explicitly:

{
  "build": {
    "framework": "nuxt"
  }
}

The accepted values are exactly:

• nextjs, static
• nuxt, solidstart, analog, tanstack-start, sveltekit, astro, react-router, remix, angular, qwik
• gatsby, docusaurus, vitepress, eleventy, hugo, jekyll, mkdocs
• nestjs, express, fastify, hono, koa
• vite, create-react-app
• laravel, symfony, wordpress, rails, django, phoenix
• fastapi, flask, spring-boot, dotnet, go, rust, php

An explicit build.framework wins over automatic detection, even when a root Dockerfile.nitroship or Dockerfile exists. You cannot set both build.framework and build.dockerfile; that combination is an error. To use your own Dockerfile instead, remove build.framework. See Dockerfile.

Without build.framework, detection uses this order:

1. The file configured by build.dockerfile, otherwise a root Dockerfile.nitroship, then a root Dockerfile.
2. Next.js, using its dedicated adapter.
3. The managed framework registry.
4. Generic static files if no framework is detected.

Managed presets produce one of four output kinds:

The kind depends on the framework and its configuration; it is not a value for build.framework. For example, Astro can produce static files or a standalone Node.js server. Local deployment supports static and Node.js outputs, including managed Next.js builds; container and container-static presets require hosted builds.

Compute settingsCopy Anchor Link

The region and size used to run servers (Next.js, managed Node.js and container presets, or your Dockerfile). Set them under App Settings > Compute in the console or in compute in nitroship.json at the deployment root. Static-only deployments do not need compute settings.

{
  "compute": {
    "regions": ["kr-icn"],
    "tier": "standard",
    "minInstances": 0,
    "maxInstances": 4,
    "port": 3000
  }
}

Generated Go/Rust images set PORT (default 3000), but Go/Rust apps must read it and bind to 0.0.0.0:$PORT themselves; the preset cannot change a hard-coded bind address.

On a normal deploy, when a field is set in several places, the first value found for that field wins:

1. CLI flags (direct uploads with --local, --image, or --bundle-dir only)
2. nitroship.json
3. App settings saved through App Settings > Compute in the console or the compute settings API
4. Defaults

Values are locked in when a build starts; saving app settings alone does not change an existing deployment. Console/API editing is always allowed, including regions, tier, instance limits, and port declared in nitroship.json. Use Apply now to redeploy production without rebuilding: non-null console/API values win over the previous deployment's file- or flag-sourced values for that redeploy, while fields left unset retain their previous values.

On every normal deploy, nitroship.json re-applies its declared fields over console/API settings; supported CLI flags still win over the file. Thus Apply now can temporarily override file values, but the next normal deploy restores the precedence above. See Managing deployments.

Cron settingsCopy Anchor Link

Declare crons at the top level of nitroship.json, or manage jobs in App Settings > Cron Jobs or through the Cron jobs API. Console/API edits are always allowed and apply immediately. On every production deploy that declares crons (including an empty array), the deployment's list overrides the console list again. A production deployment that does not declare crons falls back to the saved console list; remove the crons key and deploy to hand control back to the console. See Cron jobs.

How readiness is checkedCopy Anchor Link

Before a new instance takes requests, Nitroship checks that your app is ready.

• With an empty healthPath (not set, or ""): the app counts as ready once its server port accepts connections.
• With a healthPath (including /): Nitroship sends that path a GET request; 2xx, 3xx, and 404 count as ready. Each attempt waits up to 2 seconds for response headers and is retried.
• Either way, the overall limit is 30 seconds.

A healthPath you set yourself overrides the framework default (/__nitroship/health for Next.js). Older deployments that stored / keep the HTTP check through redeploys, promotions, and rollbacks.