Installing the CLI

This section contains instructions for installing the command-line interface.

There are two versions of The Things Stack CLI: ttn-lw-cliand tti-lw-cli. For most users, ttn-lw-cli is sufficient, as it supports all commands to manage The Things Stack. tti-lw-cli has additional commands for tenant management, but is otherwise identical.

We recommend that Cloud, Community Edition, and Open Source users install ttn-lw-cli, and Enterprise users install tti-lw-cli.

macOS

$ brew install TheThingsNetwork/lorawan-stack/ttn-lw-cli
Note:
When installing with brew, auto completion is enabled automatically.

To upgrade the CLI if it is already installed, use:

$ brew upgrade TheThingsNetwork/lorawan-stack/ttn-lw-cli

Linux

$ sudo snap install ttn-lw-stack
$ sudo snap alias ttn-lw-stack.ttn-lw-cli ttn-lw-cli
Note:
When installing with snap, auto completion is enabled automatically.

To upgrade the CLI if it is already installed, use:

$ sudo snap refresh ttn-lw-stack

Binaries

You can download pre-built binaries for your operating system and processor architecture.

macOS

$ brew install TheThingsIndustries/lorawan-stack/tti-lw-cli
Note:
When installing with brew, auto completion is enabled automatically.

To upgrade the CLI if it is already installed, use:

$ brew upgrade TheThingsIndustries/lorawan-stack/tti-lw-cli

Linux

$ sudo snap install tti-lw-stack
$ sudo snap alias tti-lw-stack.tti-lw-cli tti-lw-cli
Note:
When installing with snap, auto completion is enabled automatically.

To upgrade the CLI if it is already installed, use:

$ sudo snap refresh tti-lw-stack

Configuration

The command-line needs to be configured to connect to The Things Stack. You have multiple options to make the configuration file available to the CLI:

  1. Environment: export TTN_LW_CONFIG=/path/to/ttn-lw-cli.yml
  2. Command-line flag: -c /path/to/ttn-lw-cli.yml
  3. Save as .ttn-lw-cli.yml in $XDG_CONFIG_HOME, your home directory, or the working directory.
Warning:
When using the snap packages, ~/.ttn-lw-cli.yml will fail with permission errors. Choose a different path.
Note:
The default configuration file for both Open Source and Enterprise versions of the CLI is named .ttn-lw-cli.yml.

Generate configuration file

If using The Things Stack Community Edition by The Things Network or The Things Stack Cloud, visit the addresses page for The Things Network or The Things Stack Cloud to find CLI configuration files for these deployments.

If hosting your own deployment, for example at thethings.example.com, all you need is:

$ ttn-lw-cli use thethings.example.com [--fetch-ca] [--user] [--overwrite]
Warning:
If configuring ttn-lw-cli for The Things Stack Cloud, see Cloud Addresses for information about endpoints.
Note:
On Windows, use ttn-lw-cli.exe instead of ttn-lw-cli. 
$ tti-lw-cli use thethings.example.com [--fetch-ca] [--user] [--overwrite]
Note:
On Windows, use tti-lw-cli.exe instead of tti-lw-cli.

This will generate and save the required CLI config file. By default, the file is saved on the current directory, use the --user to save it under the user config directory.

If the deployment is using a CA that is not already trusted by your system, use the --fetch-ca flag to also connect to the server and retrieve the CA required for establishing secure communication.

If the file exists already, it is not overwritten and an error is printed instead. You can use --overwrite to overwrite the existing configuration file.

Note:
You can also use the --grpc-port and --oauth-server-address flags to override the default values for the gRPC port and the OAuth server address. These are not needed for standard deployments.
Note:

If you are using an https port other than 443 (for example if you are running The Things Stack on localhost), you need to specify the OAuth server address by appending the --oauth-server-address="https://thethings.example.com:8885/oauth" flag when running the CLI.

If you are using a custom certificate authority, you will have to specify the --ca="/path/to/ca.pem" flag when running the CLI.

Manually create configuration file

If using The Things Network or The Things Stack Cloud, visit the addresses page for The Things Network or The Things Stack Cloud to find CLI configuration files for these deployments.

If hosting your own deployment, you can create a file named .ttn-lw-cli.yml and paste the following contents:

oauth-server-address: 'https://thethings.example.com/oauth'

identity-server-grpc-address: 'thethings.example.com:8884'
gateway-server-grpc-address: 'thethings.example.com:8884'
network-server-grpc-address: 'thethings.example.com:8884'
application-server-grpc-address: 'thethings.example.com:8884'
join-server-grpc-address: 'thethings.example.com:8884'
device-claiming-server-grpc-address: 'thethings.example.com:8884'
device-template-converter-grpc-address: 'thethings.example.com:8884'
qr-code-generator-grpc-address: 'thethings.example.com:8884'
Warning:
If configuring ttn-lw-cli for The Things Stack Cloud, see Cloud Addresses for information about endpoints.

If you are using an https port other than 443 (for example if running The Things Stack on localhost), you need to specify that port, e.g.:

oauth-server-address: 'https://thethings.example.com:8885/oauth'

If your deployment uses a custom certificate authority, you will need to add the following line in the configuration file:

ca: /path/to/ca.pem

For advanced options, see the Configuration Reference.

Auto Completion

Auto completion allows the shell to automatically fill in commands after you type the first few letters. It is completely optional but can save you time entering commands.

Use ttn-lw-cli complete to generate an auto completion script for the ttn-lw-cli command. bash, zsh, fish and powershell shells are supported:

$ ttn-lw-cli complete --shell bash --executable ttn-lw-cli > ttn-lw-cli-autocomplete

Source the file to enable auto completion:

$ . ./ttn-lw-cli-autocomplete

Alternatively, put in a default directory so that it is loaded automatically (this directory depends on your Operating System and your shell).

For bash, this directory is typically /etc/bash_completion.d/:

$ sudo cp ./ttn-lw-cli-autocomplete /etc/bash_completion.d/

Generating and sourcing an auto completion PowerShell script on Windows is slightly modified:

$ ttn-lw-cli.exe complete --shell powershell --executable ttn-lw-cli.exe > ttn-lw-cli-autocomplete.ps1

$ . ./ttn-lw-cli-autocomplete.ps1

Use tti-lw-cli complete to generate an auto completion script for the tti-lw-cli command. bash, zsh, fish and powershell shells are supported:

$ tti-lw-cli complete --shell bash --executable tti-lw-cli > tti-lw-cli-autocomplete

Source the file to enable auto completion:

$ . ./tti-lw-cli-autocomplete

Alternatively, put in a default directory so that it is loaded automatically (this directory depends on your Operating System and your shell).

For bash, this directory is typically /etc/bash_completion.d/:

$ sudo cp ./tti-lw-cli-autocomplete /etc/bash_completion.d/

Generating and sourcing an auto completion PowerShell script on Windows is slightly modified:

$ tti-lw-cli.exe complete --shell powershell --executable tti-lw-cli.exe > tti-lw-cli-autocomplete.ps1

$ . ./tti-lw-cli-autocomplete.ps1

← Command-line Interface Login with the CLI →