Skip to main content
The CLI reads its settings from a TOML config file. There are two kinds: a global config tied to your account, and an optional project-local .appsignal.toml that takes over inside a project. This page covers the project command, where each file lives, and every key you can set.

​
The project command

appsignal-cli project init creates or updates a project-local .appsignal.toml:
Shell
appsignal-cli project init
If you run it inside a git checkout, the CLI writes .appsignal.toml at the repository root. Outside a git checkout, it uses the current directory. You can set the project’s default organization as you create the file:
Shell
appsignal-cli project init --org <YOUR_ORG_SLUG>
project init accepts these flags:
FlagDescription
--org <slug>Set the default organization for the project
--endpoint <url>Point the project at a non-production AppSignal server
--rest-endpoint <url>Point the project at a non-production REST or public API base URL
--oauth-client-id <id>Override the OAuth client ID for the project
project init doesn’t copy your global OAuth credentials into the project file. After creating it, run appsignal-cli auth login inside the project to set up project-specific credentials.
Don’t commit .appsignal.toml to version control. Once you authenticate, it holds your OAuth tokens. Add it to your .gitignore.

​
Where config lives

The global config lives in your operating system’s standard config directory; its exact path varies by OS. Run appsignal-cli auth status to see where yours is. It holds your account-wide credentials and default organization. A project-local .appsignal.toml can live anywhere in a project. When the CLI runs inside that project or a subdirectory, it uses the nearest .appsignal.toml as the only config for that project. When a project-local config is active, the CLI reads and writes only that file. Otherwise, it uses the global config. The org value is saved automatically when you run appsignal-cli apps list or appsignal-cli apps set-org --org <slug>, into whichever config is active. Run project init first if you want those writes to stay local to the project.

​
Config keys

Both files use the same keys:
KeyDescription
orgDefault organization slug, used when a command omits --org.
[oauth] tableOAuth credentials (access_token, refresh_token, expires_at). Set automatically by appsignal-cli auth login.
A global config looks like this:
Global config
org = "<YOUR_ORG_SLUG>"

# Set automatically by `auth login`:
[oauth]
access_token = "..."
refresh_token = "..."
expires_at = 1742324400
A project-local .appsignal.toml uses the same format. OAuth tokens are refreshed automatically before API calls, so you don’t have to sign in again. OAuth always uses the built-in local callback at http://127.0.0.1:9789/callback.

​
Telemetry

The CLI sends a minimal, best-effort telemetry event for each command run, to help AppSignal measure CLI usage and reliability. Each event includes only the command path, whether it succeeded or failed, how long it took, the CLI version, and the output format. It contains none of your AppSignal data. To turn it off, set APPSIGNAL_CLI_TELEMETRY=0:
Shell
APPSIGNAL_CLI_TELEMETRY=0 appsignal-cli incidents list --app "MyApp" --environment production
Set the variable in your shell profile to disable telemetry for every command.

​
Custom endpoints

Most users never need these settings. They make the CLI talk to a non-production AppSignal server instead of the default, which is mainly useful to AppSignal’s own engineers for testing. You can set them as flags on project init or auth login, or as keys in your config file. The keys are:
Config keyDescription
endpointBase URL of the AppSignal server, without /graphql. The CLI appends /graphql for API calls and uses the base URL for OAuth.
rest_endpointBase URL of the REST or public API, when it differs from endpoint.
oauth_client_idOAuth client ID to use during login. When unset, the CLI uses the production client, or registers one automatically for endpoints that advertise a registration_endpoint.
A value like https://appsignal.example.com/graphql is not supported. Use the base URL only.

​
Next steps

With your configuration in place, list your apps and start querying your data.