---
title: Services
description: List, select, alias, and override ObsessionDB services per command — and how queries route through the ObsessionDB API.
sidebar:
  order: 4
---

Once you're authenticated, the plugin manages which ObsessionDB service each command talks to. You set a default per project, override it per command, and define short aliases for the services you switch between most.

## List and select

List all services across the organizations your account belongs to:

```sh
chkit obsessiondb service list
```

Output is grouped by organization, with the currently selected service marked.

Pick one as the project default:

```sh
chkit obsessiondb service select
```

The selection is persisted to `.chkit/obsessiondb.json` next to your config file. Every `chkit` command after that uses it unless you override (see below).

Credentials and service selection live in separate files:

- **Credentials** — `~/.config/chkit/credentials.json`. The access token and API base URL, written by `login`/`signup` and shared across all projects.
- **Service selection and aliases** — `obsessiondb.json`. Stored per project at `.chkit/obsessiondb.json` (next to `clickhouse.config.ts`), or at `~/.config/chkit/obsessiondb.json` when running without a project config.

### Services in another organization

The ObsessionDB API looks a service up in the active organization of the chkit login session only. That organization is set when the session is created and is separate from the one selected in the console, so switching organizations in the console does not change it. A command for a service of another organization fails with an error that names the service, the session's organization, and the organization that owns the service:

```sh
$ chkit query "SELECT 1"
obsessiondb: service "benchmarks" is not in the active organization "Acme" of this chkit session (it belongs to "Benchmarks"). ...
```

With `--json`, the error code is `service_not_in_active_organization`, or `service_not_found` when no organization you belong to has the service. Select a service from the session's organization with `chkit obsessiondb service select`.

## Per-command override

Any command that hits ClickHouse accepts `--service <name-or-alias>` to target a different service for one invocation without changing the saved selection:

```sh
# Ad-hoc query against a different service
chkit query "SELECT count() FROM users" --service customer-b

# Apply migrations against a one-off service
chkit migrate --apply --service staging
```

`--service` is available on `generate`, `migrate`, `status`, `drift`, `check`, `query`, and `pull`.

The lookup tries service names first (as shown in `chkit obsessiondb service list`), then saved aliases. If nothing matches, the command fails fast with the list of available services and aliases.

## Aliases

Aliases give your services short, memorable names. Set, list, and remove them with `service alias`:

```sh
# Define a short alias for a service
chkit obsessiondb service alias set prod customer-production

# Use the alias anywhere --service is accepted
chkit query "SELECT count() FROM users" --service prod

# List or remove aliases
chkit obsessiondb service alias list
chkit obsessiondb service alias remove prod
```

Aliases live in the same file as the service selection: `.chkit/obsessiondb.json` next to your config, or `~/.config/chkit/obsessiondb.json` when running without a project config. The TypeScript CLI and chkit-py read and write the same file, so an alias set with one resolves in the other.

Aliases can't shadow real service names — if `prod` is already the name of a service, setting it as an alias is rejected. An alias also can't start with `-`, which the command line would read as a flag.

## Remote query routing

When a service is selected, chkit doesn't open a direct ClickHouse connection. SQL from `chkit query` and any plugin command that runs queries is submitted through the ObsessionDB API to the selected service, and results are normalized back into chkit's executor interface.

This is why no `clickhouse` block is required in `clickhouse.config.ts` once you're authenticated — the plugin supplies the executor.

See [`chkit query`](/cli/query/) for the command reference, including the `--service` flag and JSON output.

## Related

- [`chkit query`](/cli/query/) — ad-hoc SQL execution against the selected service.
- [Engine Rewriting](/obsessiondb/engine-rewriting/) — how `Shared*` engines and `storage_policy` are handled for ObsessionDB and regular ClickHouse targets.
- [Backfill Jobs](/obsessiondb/backfills/) — submit backfills as managed jobs to the selected service.
