Configuring the CLI

The Things Stack CLI needs to be configured to connect to your The Things Stack deployment.

To configure the CLI, you first have to create a configuration file, then make that file available to the CLI. The CLI configuration file can be generated or manually created.

Step 1 - Create a configuration file

Automatically generate configuration file

To generate the CLI configuration file, use the following command in your terminal:

Cloud, Sandbox, and Open Source
Enterprise

If using The Things Stack Sandbox, use the following command as per your regional cluster:

ttn-lw-cli use <eu1/au1/nam1>.cloud.thethings.network

or on Windows, this would be:

ttn-lw-cli.exe use <eu1/au1/nam1>.cloud.thethings.network

If you are using The Things Stack Cloud use the following command with your tenant id and regional cluster.

ttn-lw-cli use <tenant_id>.<eu1/eu2/au1/nam1/>.cloud.thethings.industries

If you are hosting your own deployment, use the following, replacing thethings.example.com with your server address:

ttn-lw-cli use thethings.example.com

If you are hosting your own deployment, use the following, replacing thethings.example.com with your server address:

tti-lw-cli use thethings.example.com

or on Windows:

tti-lw-cli.exe use thethings.example.com

This will generate the CLI configuration and save it to a file named .ttn-lw-cli.yml.

By default, the file is created in the current directory. Add the --user flag to save it under the user’s .config directory. The last INFO line in response to running the command will contain the location of the generated file:

INFO	Config file for eu1.cloud.thethings.network written in /home/user/.config/.ttn-lw-cli.yml

Note:

The default configuration file for both ttn-lw-cli and tti-lw-cli CLI versions is named .ttn-lw-cli.yml.

Once you have the configuration file, proceed to Step 2 - Configure CLI to pass the configuration file to the CLI.

Additional Flags (Optional)

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, i.e:

tti-lw-cli use thethings.example.com --fetch-ca

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

If the configuration file already exists and you run the command to generate it again, it will not be overwritten by default and an error will be printed instead. Use --overwrite to overwrite the existing configuration file.

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. Note that these are not needed for standard deployments. An example of having to specify the --oauth-server-address is if you are using an https port other than 443, for example if you are running The Things Stack on localhost. In case of running The Things Stack on localhost, you need to append --oauth-server-address="https://localhost:8885/oauth when running the CLI.

Manually create configuration file

It is also possible to manually create a configuration file. For most configurations, this is not necessary, and it is preferable to automatically generate the configuration. However, if you have separate component addresses, you can specify them in a manual configuration.

To manually configure, first create a .ttn-lw-cli.yml file.

Copy and paste the following contents in the .ttn-lw-cli.yml file, replacing thethings.example.com with the server addresses of each component:

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"

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 by adding the following line in .ttn-lw-cli.yml:

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

If your deployment uses a custom certificate authority, you will need to specify the path to the CA file by adding the following line in the configuration file:

ca: /path/to/ca.pem

For advanced options, see the Configuration Reference.

Step 2 - Configure the CLI

Once you have the .ttn-lw-cli.yml configuration file, you have multiple options to make this file available to the CLI in order to configure it:

Save the configuration file as .ttn-lw-cli.yml in $XDG_CONFIG_HOME, your home directory, or the working directory. If you automatically generate configuration using ttn-lw-cli use, the configuration will be saved in the working directory.
Set the environmental variable by running:

macOS and Linux:

export TTN_LW_CONFIG=/path/to/.ttn-lw-cli.yml

Windows:

set TTN_LW_CONFIG=/path/to/.ttn-lw-cli.yml

Use command-line flag -c /path/to/.ttn-lw-cli.yml when running the CLI

Warning:

When using the snap packages, ~/.ttn-lw-cli.yml will fail with permission errors. Choose a different path for the configuration file.

To check if configuration is being properly loaded, use the following command:

ttn-lw-cli config

or on Windows:

ttn-lw-cli.exe config

or for Enterprise deployments:

tti-lw-cli config

Once the CLI has been configured, proceed to Login with the CLI to authorize and begin using the CLI.

← Installing the CLI Login with the CLI →