Northflank CLI

Provides a command-line interface (CLI) to the Northflank platform.

Visit our website www.northflank.com

Full documentation on https://northflank.com/docs/v1/api/use-the-cli

Also use the Northflank js-client: https://www.npmjs.com/package/@northflank/js-client

Please don’t hesitate to get in touch with us if you have a query or want to give some feedback on https://northflank.com/contact or email us at [email protected].

Installation

Install with npm i @northflank/cli -g or yarn global add @northflank/cli.

This allows to use the CLI globally from the command line.

To use without installation, run npx @northflank/cli

Usage

The command northflank help provides useful information in navigating the various commands of the CLI.

Login

Run the login command to connect the CLI to your northflank account:

northflank login

You will be asked to provide an API token. The token can be created using the Northflank web interface: Account Settings > API > Tokens > Create API token.

This creates a context, which will be used as a default for further use of the CLI.

Environment context

For headless use, CI, containers, and agent-driven development, the CLI can use an API token directly from the environment without reading or writing ~/.northflank/config.json:

NF_API_TOKEN=<token> northflank list projects

NORTHFLANK_API_TOKEN is accepted as a long-form alias. The API base URL defaults to https://api.northflank.com and can be overridden with NF_API_BASE_URL (or NORTHFLANK_API_BASE_URL).

To keep persistent contexts outside the home directory, set NF_CONFIG_DIR (or NORTHFLANK_CONFIG_DIR). The CLI will read and write config.json inside that directory:

NF_CONFIG_DIR="$PWD/.northflank-config" northflank login

Having logged in, the CLI is ready to be used.

Examples

• Listing services in a project: northflank list services
• Getting detailed information about a service: northflank get service
• Scaling a service: northflank scale service
• Creating a combined service: northflank create service combined

Contexts

Contexts can be used to cache auth info, default projects and services:

• northflank contexts use project
• northflank contexts use service
• northflank context use and its resource subcommands update only the global context.
• List all context and defaults: northflank contexts list
• Switch between contexts: northflank context use

Repository resource context

A repository can provide non-secret command defaults in northflank.yaml:

context:
  team: my-team
  project: my-project
  service: my-service

The CLI checks the current directory, then the Git root (never intermediate directories). Outside Git, only the current directory is checked. Precedence is: command options, this file, then global defaults; --noDefaults ignores both kinds of defaults. A present file is a complete local resource context, so omitted fields do not fall back globally. Invalid files warn and disable global resource defaults until fixed or removed, but do not stop the command.

Supported keys are team, project, service, job, addon, volume, and harness. Keep API tokens, secrets, and endpoints in environment variables or the global CLI context.

Forwarding Northflank Services and Addons

Northflank services and addons can be exposed locally using the northflank forward command. Examples:

• sudo northflank forward all
• sudo northflank forward addon --addonId <addon-id>
• sudo northflank forward service --serviceId <service-id>

Root/admin privileges are required when local hostnames are configured. Use --skipHostnames to forward only on loopback IP addresses without changing the hosts file. If a preferred local port is unavailable or requires privileges, the default --portConflict random mode selects an available port and prints the reassignment. Use --portConflict prompt to choose interactively, or --portConflict fail to stop with an error instead.

Interactive Mode

The CLI will ask for the required information when executing a command if the information is not provided by command line arguments or input files. This is done in a beginner-friendly question-answer style of interacting and allows for CLI exploration.

After having provided all required information, the user can choose to run through the questions again or edit the final command payload for full flexibility. The request can also be saved to a file and be used in the future using the --file <file-path> flag.