@northflank/cli/README.md

Provides a command-line interface to the Northflank platform.

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

*Visit our website [www.northflank.com](https://www.northflank.com)*

*Full documentation on [https://northflank.com/docs/v1/api/use-the-cli](https://northflank.com/docs/v1/api/use-the-cli)*

*Also use the Northflank js-client: [https://www.npmjs.com/package/@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](https://northflank.com/contact)
or email us at [contact@northflank.com](mailto:contact@northflank.com).

### 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`<br />

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. 

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: <br>
- `northflank contexts use project`
- `northflank contexts use service`
- List all context and defaults: `northflank contexts list`
- Switch between contexts: `northflank context use`

#### 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>`

__Please note that this command requires root/admin privilges__

#### 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.