From a6830eda44d832100dd7789ef82696e7e9d085ba Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Sun, 11 Oct 2026 10:11:17 -0400 Subject: [PATCH 1/2] docs(cli): document multi-account use, login --wait and whoami --output json [RED-1122] Documents checkly/checkly-cli#1528: - authentication: a "Working with several accounts" section (default account, `CHECKLY_ACCOUNT_ID` for one command or pinned in a shell or `.env`), and that only `CHECKLY_API_KEY` switches to API key credentials. - checkly login: `--wait`, the AI agent flow without "tell me when you're done", and how the two environment variables affect the login. - checkly whoami: the default and other accounts, `--output json` and its fields, and the inline login when not authenticated. - checkly switch: what it does without a terminal or under an AI agent, and the `CHECKLY_ACCOUNT_ID` precedence warning. Co-Authored-By: Claude Opus 5.5 (1M context) --- cli/authentication.mdx | 16 ++++++++++++++++ cli/checkly-login.mdx | 11 ++++++++--- cli/checkly-switch.mdx | 13 +++++++++++-- cli/checkly-whoami.mdx | 41 +++++++++++++++++++++++++++++++++-------- 4 files changed, 68 insertions(+), 13 deletions(-) diff --git a/cli/authentication.mdx b/cli/authentication.mdx index 6c1c2f37..48b68fd9 100644 --- a/cli/authentication.mdx +++ b/cli/authentication.mdx @@ -34,6 +34,20 @@ To log out and clear your stored credentials: npx checkly logout ``` +## Working with several accounts + +Your `checkly login` belongs to you, not to one account, so it works with every account you're a member of. Commands use your default account, which you choose when you log in and change with `checkly switch`. + +To use another account for a single command without changing the default, set `CHECKLY_ACCOUNT_ID` on that command: + +```bash Terminal +CHECKLY_ACCOUNT_ID=a43... npx checkly test-sessions get +``` + +`checkly whoami` lists your accounts and their IDs. When a lookup by ID finds nothing, the error names the account that was searched, so you can try another. + +`CHECKLY_ACCOUNT_ID` in your shell or a project's `.env` file works the same way for every command until you remove it, whatever your default is. A project can use this to pin its account while each developer logs in with their own `checkly login`. Without a stored login, the first command logs you in and then uses that account. `checkly whoami` shows when the variable picks the account, and `checkly switch` and `checkly login` warn that it takes precedence over the default they store. A variable set on the command line wins over the value in `.env`. + ## From CI You can also authenticate using environment variables, which is useful for CI/CD pipelines and automated environments. @@ -42,6 +56,8 @@ You will need to export two environment variables in the shell: - `CHECKLY_API_KEY` - `CHECKLY_ACCOUNT_ID` +Setting `CHECKLY_API_KEY` switches the CLI to API key credentials: it ignores any stored login, and `checkly login` refuses to run until you remove the variables. A `CHECKLY_ACCOUNT_ID` without `CHECKLY_API_KEY` only picks the account for your login (see above); in CI, where no login can happen, the CLI asks you to set `CHECKLY_API_KEY` as well. + To get your API key, go to your Settings page in Checkly and grab a API key from [the API keys tab](https://app.checklyhq.com/settings/user/api-keys) and your Account ID from the [Account settings tab](https://app.checklyhq.com/settings/account/general). Set the account ID and API key as follows: diff --git a/cli/checkly-login.mdx b/cli/checkly-login.mdx index 501ed5f9..afb19476 100644 --- a/cli/checkly-login.mdx +++ b/cli/checkly-login.mdx @@ -51,6 +51,7 @@ To create checks for a project, run `npx checkly init`. |---|---| | `--account-id ` | Use this account instead of asking which one. When you're already logged in, switch to it without logging in again. | | `--no-browser` | Only print the URL and code; don't try to open a browser. Setting `CHECKLY_NO_BROWSER=1` does the same, e.g. on headless hosts. | +| `--wait` | For AI agents: wait until you approve the code an earlier run showed, instead of returning at once. | ## Authentication Flow @@ -66,7 +67,7 @@ Commands that need authentication start the same login when no credentials are s ### AI agents -When the CLI runs under an AI agent, `checkly login` prints a JSON line with the URL and code for the agent to pass on to you, and exits instead of waiting. After you've approved the login in the browser, the agent runs the command again to finish it. In CI, set [environment variables](/cli/authentication#from-ci) instead. +When the CLI runs under an AI agent, `checkly login` prints a JSON line with the URL and code for the agent to pass on to you, and exits instead of waiting. The agent then runs `npx checkly login --wait`, which returns as soon as you've approved the login in the browser, so you don't have to tell the agent when you're done. If you have several accounts, the agent asks you which one to use. In CI, set [environment variables](/cli/authentication#from-ci) instead. ### New Users @@ -106,9 +107,13 @@ Run [`checkly logout`](/cli/checkly-logout) first, then `checkly login` again. ### Multiple accounts -If you have access to multiple Checkly accounts, you'll be prompted to select which account to use as the active account for CLI operations. +If you have access to multiple Checkly accounts, you'll be prompted to select which account to use as the default account for CLI operations. -You can also switch accounts later using [`checkly switch`](/cli/checkly-switch) or `checkly login --account-id `. +You can also switch accounts later using [`checkly switch`](/cli/checkly-switch) or `checkly login --account-id `, or use another account for a single command with `CHECKLY_ACCOUNT_ID`. See [Working with several accounts](/cli/authentication#working-with-several-accounts). + +### Environment variables + +While `CHECKLY_API_KEY` is set, the CLI uses API key credentials and `checkly login` refuses to run; remove the variables to log in. A `CHECKLY_ACCOUNT_ID` on its own doesn't stop the login: it picks the account, so the login finishes without asking and stores no default. ## Related Commands diff --git a/cli/checkly-switch.mdx b/cli/checkly-switch.mdx index 739a8bdb..df465f93 100644 --- a/cli/checkly-switch.mdx +++ b/cli/checkly-switch.mdx @@ -18,12 +18,21 @@ If you only have access to one account, this command will indicate no alternativ ## Usage -The basic command displays available accounts and provides an interactive selection interface. +The basic command displays available accounts and provides an interactive selection interface. It changes the default account: the one commands use from then on. ```bash Terminal npx checkly switch [options] ``` +Without a terminal to answer the menu, `checkly switch` lists the accounts instead: + +- In CI and other runs without a terminal, it fails with the available accounts and the `--account-id` command to use. +- Under an AI agent, it prints a JSON line with the default account and the choices, so the agent can ask you which account to use. + +To use another account for a single command without changing the default, set `CHECKLY_ACCOUNT_ID` on that command instead. See [Working with several accounts](/cli/authentication#working-with-several-accounts). + +While `CHECKLY_ACCOUNT_ID` is set (on the command line, in your shell or in `.env`), commands use that account instead of the default. `checkly switch` still changes the stored default, and warns that the variable takes precedence. + | Option | Required | Description | |--------|----------|-------------| | `--account-id, -a` | - | The id of the account you want to switch to. | @@ -67,7 +76,7 @@ npx checkly switch npx checkly switch --account-id="a43....." # Output -Account switched to "a43....." +Account switched to Staging (a43.....) ``` diff --git a/cli/checkly-whoami.mdx b/cli/checkly-whoami.mdx index d63769e4..a029743e 100644 --- a/cli/checkly-whoami.mdx +++ b/cli/checkly-whoami.mdx @@ -5,18 +5,20 @@ sidebarTitle: 'checkly whoami' canonical: 'https://www.checklyhq.com/docs/cli/checkly-whoami/' --- -The `checkly whoami` command displays detailed information about your current Checkly authentication, including the logged-in user account and active Checkly account details. - -This command can also be run without authentication to check your current status. +The `checkly whoami` command shows which user and Checkly account the CLI uses, your default account, and the other accounts your login works with. ## Usage The basic command shows current authentication status and account information. ```bash Terminal -npx checkly whoami +npx checkly whoami [options] ``` +| Option | Required | Description | +|--------|----------|-------------| +| `--output, -o` | - | Output format: `detail` (default) or `json`. | + ### Authenticated @@ -25,18 +27,41 @@ If you're logged in, you'll see: ```bash Terminal npx checkly whoami -You are currently on account "Monitoring as Code" (b2f...) as raccoon@checklyhq.com. +You are currently on account "Monitoring as Code" (b2f...) as Raccoon. +Default account: "Monitoring as Code" (b2f...) +Other accounts: "Staging" (a43...) +``` + +The default account is the one commands use unless `CHECKLY_ACCOUNT_ID` picks another; see [Working with several accounts](/cli/authentication#working-with-several-accounts). When it does, `whoami` names the account in use and says that the variable takes precedence over the default. + +### JSON output + +`--output json` returns the same information for scripts and AI agents: + +```bash Terminal +npx checkly whoami --output json ``` +```json +{ + "user": { "id": "...", "name": "Raccoon" }, + "account": { "id": "b2f...", "name": "Monitoring as Code", "plan": "Team", "addons": [] }, + "accountSource": "login", + "defaultAccount": { "id": "b2f...", "name": "Monitoring as Code" }, + "otherAccounts": [{ "id": "a43...", "name": "Staging" }] +} +``` + +`accountSource` is `login` (your stored login and default account), `account_override` (`CHECKLY_ACCOUNT_ID` picks the account for your login) or `environment` (API key credentials from `CHECKLY_API_KEY`). `defaultAccount` is `null` when no default is stored, and for API key credentials, which don't use it. + ### Not Authenticated -If not logged in, you'll see: +In a terminal or under an AI agent, `whoami` starts [`checkly login`](/cli/checkly-login) first when no credentials are stored. Elsewhere, such as in CI, it fails: ```bash Terminal npx checkly whoami -Error: Run `npx checkly login` or manually set `CHECKLY_API_KEY` & `CHECKLY_ACCOUNT_ID` -environment variables to setup authentication. +Error: Run `npx checkly login` or set `CHECKLY_API_KEY` & `CHECKLY_ACCOUNT_ID` in your environment or .env file. ``` ## Related Commands From 7fe87d75719b66ecc5a28835fddbee441d44d2eb Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Mon, 12 Oct 2026 10:34:06 -0400 Subject: [PATCH 2/2] docs(cli): match whoami's account list format [RED-1122] Co-Authored-By: Claude Opus 5.5 (1M context) --- cli/checkly-whoami.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/checkly-whoami.mdx b/cli/checkly-whoami.mdx index a029743e..ecc7b759 100644 --- a/cli/checkly-whoami.mdx +++ b/cli/checkly-whoami.mdx @@ -28,8 +28,8 @@ If you're logged in, you'll see: npx checkly whoami You are currently on account "Monitoring as Code" (b2f...) as Raccoon. -Default account: "Monitoring as Code" (b2f...) -Other accounts: "Staging" (a43...) +Default account: Monitoring as Code (b2f...) +Other accounts: Staging (a43...) ``` The default account is the one commands use unless `CHECKLY_ACCOUNT_ID` picks another; see [Working with several accounts](/cli/authentication#working-with-several-accounts). When it does, `whoami` names the account in use and says that the variable takes precedence over the default.