Configuration - AppSignal Documentation

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:

Flag	Description
`--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:

Key	Description
`org`	Default organization slug, used when a command omits `--org`.
`[oauth]` table	OAuth 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 key	Description
`endpoint`	Base URL of the AppSignal server, without `/graphql`. The CLI appends `/graphql` for API calls and uses the base URL for OAuth.
`rest_endpoint`	Base URL of the REST or public API, when it differs from `endpoint`.
`oauth_client_id`	OAuth 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.

​The project command

​Where config lives

​Config keys

​Telemetry

​Custom endpoints

​Next steps

The `project` command

Where config lives

Config keys

Telemetry

Custom endpoints

Next steps