Dibbla Docs Get started Guides Workflows Changelog
Open Console
Reference · CLI

dibbla context

Stay logged in to several Dibbla API servers at once — production, a self-hosted instance, a customer's — and switch between them with one command instead of logging in again.

A context is a named login target: an API URL, the token for it, and the organization you act as on that server. Several exist side by side, so logging in to a second Dibbla instance no longer replaces the first.

dibbla login --context prod --api-key=<token>
dibbla login --context acme --api-url https://api.example.com --api-key=<token>

dibbla context list          # both, with the one in use marked
dibbla apps list --context prod   # just this command
dibbla context use acme      # from now on

If you only ever talk to one Dibbla server, you can ignore this page entirely. Your login was turned into a context called prod the first time you ran the CLI after upgrading, and nothing about your workflow changed.

Commands

The group answers to dibbla context, dibbla contexts and dibbla ctx.

CommandWhat it does
dibbla context listList the configured contexts, marking the one in use. Alias: ls.
dibbla context use <name>Talk to that server from now on.
dibbla context currentPrint the name the next command would actually use.
dibbla context rename <old> <new>Rename a context, moving its stored token with it.
dibbla context rm <name>Remove a context and the token stored for it.

Flags

FlagOnPurpose
--jsonlistMachine-readable output. Each row carries current and logged_in.
--forcermRequired to remove the context you are currently using.
--context <name>every commandUse that context for this one invocation, without changing what is selected.

Which server does a command use?

The first hit wins:

  1. DIBBLA_API_TOKEN / DIBBLA_API_URL in the shell environment.
  2. The same two in ./.env, loaded automatically at startup.
  3. --context <name>.
  4. DIBBLA_CONTEXT in the environment.
  5. The context selected with dibbla context use.
  6. https://api.dibbla.com.
CI and scripted calls are unaffected.

With DIBBLA_API_TOKEN set — or when the CLI detects a CI environment — no configuration file and no keyring entry is read at all. Contexts sit strictly below the environment, so a one-shot DIBBLA_API_TOKEN=… dibbla apps list behaves exactly as it did before contexts existed.

Two things are errors rather than quiet fallbacks, on purpose: naming a context that does not exist, and a config.yaml that will not parse. Silently dropping you onto the production endpoint when you believed you were somewhere else is the one outcome a multi-server tool must not have.

Where things are stored

WhatWhere
The list of contexts (no secrets)~/.config/dibbla/config.yaml
Each context’s tokenThe OS keyring, under a per-context key
Token, on a host with no keyring~/.config/dibbla/credentials.<name>.env, mode 0600

config.yaml is a plain file you can read and edit:

current: acme
contexts:
  prod:
    api_url: https://api.dibbla.com
  acme:
    api_url: https://api.example.com
    org: org_...

It is a file rather than more keyring entries for one reason: no operating system offers a portable way to enumerate everything stored under a service, so dibbla context list could not be made reliable on macOS, Windows and Linux alike. Since the list holds no secrets, being an inspectable file is a feature.

Organizations are per context

dibbla org use stores your choice on the context you are using, and dibbla org list shows the organizations on that context’s server.

An organization id is issued by, and only means anything on, the server that issued it. Sending one server’s organization to another is a wrong-organization read or write, so the two are nested rather than independent: switching context switches organization with it. A context with nothing pinned sends no organization at all, and the API uses your account’s default on that server.

Upgrading from a single login

Nothing to do. The first time you run the upgraded CLI, your existing login is imported into a context, keeping its organization. You are not asked to log in again.

The name is derived from the server: the default endpoint becomes prod, and anything else takes the first label after api. — api.acme.example.com becomes acme. Rename it if you would rather it were something else.

An older dibbla on the same machine keeps working.

Whichever context is in use is mirrored into the single credential slot the CLI used before contexts existed. A dibbla binary that predates this feature — and any script that reads ~/.config/dibbla/credentials.env directly — follows dibbla context use rather than silently staying on the previous server.

Logging in and out

dibbla login adds or refreshes a context rather than replacing your credentials. It keys on the API URL: logging in to a server you already have refreshes that context’s token, and a new URL creates a new context.

FlagPurpose
--context <name>Name the context to create or refresh, instead of deriving one.
--no-switchStore the login without making it the context in use.

dibbla logout removes only the context you are using — logging out of a customer instance does not log you out of production. Use --context <name> to log out of a different one, or --all to remove every context.

`--context` means something different on `login` and `logout`.

On every other command, --context names the context to read. On login and logout it names the context to write or remove. So dibbla login --context acme adds or refreshes acme; it does not run that login “as” another context.

What contexts do not cover

dibbla update and the installer are deliberately machine-wide. They upgrade the CLI on this computer, which is not a per-server thing, and --context has no effect on either.

A generated MCP client configuration (dibbla mcp community) is written for whichever server was in use at the time. If you keep configurations for more than one instance, keep them in separate files.

Examples

# Add a self-hosted instance without disturbing your Dibbla login
dibbla login --context selfhost --api-url https://api.example.com --api-key=<token>

# Check where you are before doing something destructive
dibbla context current
dibbla status

# Run one command against another server
dibbla apps list --context prod

# Point a whole shell at one server
export DIBBLA_CONTEXT=selfhost

# Machine-readable: the API URL of the context in use
dibbla context list --json | jq -r '.[] | select(.current) | .api_url'

# Remove one you no longer need
dibbla context rm selfhost
← Previous
dibbla login