> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> How the AppSignal CLI stores its settings: the project command, the global and project-local config files, and every config key.

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

```sh Shell theme={null}
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:

```sh Shell theme={null}
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                      |

<Note>
  `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.
</Note>

<Warning>
  Don't commit `.appsignal.toml` to version control. Once you authenticate, it holds your OAuth tokens. Add it to your `.gitignore`.
</Warning>

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

```toml Global config theme={null}
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`:

```sh Shell theme={null}
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](/cli/apps) and start querying your data.