mirror of https://github.com/coralogix/cx-cli.git synced 2026-09-14 16:15:45 +08:00

Files

T

MLKEREN 811ac10db2 docs: rebuild the docs set around cx init (#206 )

## Why

`cx init` (#204) and `cx skills install` (#203) shipped without touching
the docs, and #200 replaced the region prompt the docs still describe.
The README walks users through `curl` → `npx skills add` → `cx profiles
add`: the three-step flow this quarter's work was meant to replace.

Docs only, no `src/` changes. Written with @yael-vogel and
@amitcoralogix after the Aug 20 review. The portal side is
coralogix/documentation#3737, which **reverts on the nightly sync until
this lands** (and `docs/quickstart.md` is a new file the sync expects to
exist).

## How to review this

`README.md` is -403/+15, but almost none of that is deleted content. It
moved. Suggested order:

1. **`docs/quickstart.md`** (new, 286 lines) is the page this PR exists
for. Read it as a new user with nothing installed.
2. **The movement map below**, to confirm nothing was dropped on the way
out of the README.
3. **`docs/configuration.md`**, which holds the new `cx profiles add`
and region-prompt reference. Every factual correction lives here or in
the quick start.
4. **`skills/README.md`** and **`docs/multi-profile.md`**: absorbed
README sections, plus a new `cx skills install` reference.
5. **`README.md`** last: what is left once the move is done.

### Where every README section went

| Old README section | New home | Changed on the way? |
|---|---|---|
| `## What you can do` + `## Features` | README `## What you can do` |
Merged. The two duplicated each other nearly line for line; the three
facts only Features had (command count, `toon` spill threshold,
one-command setup) survive in the merged list. |
| `## Install cx for AI agents` | quickstart `## Install manually` step
1 | The `npx skills add` step is gone, `cx init` does it. Windows and
signed-release-binary routes added. |
| `## Quick start` step 1 (`cx profiles add`) | quickstart `### 2. Run
the setup` | Rewritten around `cx init`. |
| `## Quick start` steps 2-6 (logs, metrics, spans, dashboards, semantic
search) | quickstart `## First queries` | Verbatim. |
| Commands table + Global options | quickstart `## Commands` (collapsed)
| Added `docs`, `service-catalog`, `olly`, `init`, `skills`; added
`--read-only` and `--no-console-link`; split "Agent & Local" into Agent
and Local. |
| `## Configuration` | `docs/configuration.md` | Deleted as a duplicate
of the page it pointed at. |
| `## Output formats` | configuration `## Output formats` | Notes that
`cx init` profiles default to `json`. |
| `## AI agent skills` | `skills/README.md` | The six skill names that
no longer exist are gone. |
| `## Multi-profile fan-out` | multi-profile `## The default profile` |
Expanded, see below. |
| `## Installation reference` (pin, Cargo, binaries, Nix, source) |
configuration `## Installation reference` | Verbatim, plus
checksum/signature and Windows artifact notes. |
| `## Shell completions` (managed, refresh, manual, dynamic) |
configuration `## Shell completions` | Merged with the existing "Shell
completion and profiles" section, which it had been split from. |
| `<details>` Migrating from cxctl | configuration, end of `## Shell
completions` | Verbatim. |
| `## Further reading` | README `## Further reading` | Reordered, broken
paths fixed (see Corrections). |

Everything else in the diff is new prose, concentrated in four places:
the agent-prompt path and `cx init` reference in the quick start, the
`cx profiles add` and region-prompt reference in configuration, the `cx
skills install` reference in `skills/README.md`, and the default-profile
section in `docs/multi-profile.md`.

## Corrections

- **The region prompt.** #200 removed the `Paste a Coralogix URL` menu
entry. It is now one `Region / Coralogix URL:` picker you paste into.
The docs still described the old menu, which is precisely the onboarding
failure this work set out to fix.
- **Six skills that do not exist** were listed in the README
(`cx-query-logs`, `cx-dataprime`, `cx-rum`, and others). Replaced with a
pointer rather than a second list to drift, and the four real skills
missing from the `skills/README.md` table were added.
- The commands table was missing `docs`, `service-catalog`, `olly`,
`init` and `skills`, and read "29 commands across 10 domains" against 33
across 11.
- Global options omitted `--read-only` and `--no-console-link`.
- Further reading pointed at `docs/architecture.md` and
`docs/development.md`, which live under `contributing/`.

## Reference completeness

I checked `cx profiles add` and `cx skills install` against `--help`
**and** against their prompt sequences in `src/`, because the help
output shows neither interactive prompts nor flag conflicts, and that is
where most of the gaps were.

**`cx profiles add`.** The positional `[NAME]` was undocumented,
including the fact that it becomes `default` non-interactively, so a
scripted run with no name writes the default profile. Three prompts were
missing entirely: profile name, `Reconfigure profile '<name>'?`, and
`Set '<name>' as the default profile?`. Also added `--url`'s BYOC
fallback, and why the flag is `--name` and not `--profile`. `cx profiles
list`, `delete` and `set-default` had no reference anywhere.

**`cx skills install`.** Added the flag table with its conflicts
(`--interactive` excludes `--global`, `--local` and `--agent`), the
scope prompt verbatim, the success summary, and both failure modes,
including the CI case where no scope plus no terminal requires
`--global` or `--local`. It also now states that `cx skills` is a local
command, so the credential-looking global options in its `--help` do
nothing. Reading that help invites the opposite conclusion.

## Flagged items, resolved with @yael-vogel

**1. `cx init` pins JSON output for humans too.** #204's description
says only non-interactive quick runs pin JSON, but the `if quick` branch
precedes the interactive check. Confirmed that JSON for all runs is the
intended behaviour and the PR description was wrong, so the code and
these docs are correct. The docs tell human users to pass `-o text` if
they prefer text.

**2. A pasted console URL becomes the API endpoint, path included.**
`custom_base_url_from` trims a trailing slash and adds a scheme, but
never strips path, query or fragment, so pasting
`http://myenv.example.com:4200/#/olly` stores exactly that. Confirmed as
a known gap; the team will add an API validation step (AAA check) to
catch it. Documented with a warning to trim back to scheme, host and
port in the meantime.

## Verified

Docs only, so there is no `cargo` surface to exercise. What I did check:

- Every relative link and in-page anchor across the five pages resolves.
`contributing/architecture.md`, `contributing/development.md`,
`docs/agent-setup.md`, `docs/toon-output.md` and `docs/time-syntax.md`
all exist on this branch.
- "33 commands across 11 domains" matches the commands table exactly: 11
groups, 33 rows.
- The portal preview of the identical content builds green and renders
correctly, all five pages 200 with nav and CTA behaving:
https://docs-cx-cli-one-command-setu.cx-docs-staging.pages.dev/external/cx-cli/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-25 09:18:10 +00:00

3.3 KiB

Raw Permalink Blame History

Multi-profile fan-out

A profile is one connection to Coralogix — a region or endpoint, its credentials, and a default output format. Most people end up with several: one per team, one per region, or one that returns text for reading by eye and one that returns toon for an agent to consume.

Querying several teams is where the CLI earns its keep. In the Coralogix UI you switch teams one at a time; through the MCP server it isn't really reachable at all. Here it's one flag — or one command across every team at once.

The default profile

cx init creates your first profile and makes it the default. Every command you run without -p uses that default, so day-to-day work needs no flag at all:

cx logs 'source logs | limit 10'          # runs against the default profile

The default is recorded as default_profile in ~/.cx/config.toml. To see which profiles exist and which one is default, and to change it:

cx profiles list
cx profiles set-default prod-us

Add profiles as you need them and select one explicitly with -p:

cx profiles add prod-us
cx logs 'filter $m.severity == ERROR' -p prod-us

Naming a profile you haven't created is an error rather than a silent fallback to the default:

Profile 'prod-us' not found. Run `cx profiles add` to set it up.

Fanning out

cx can also run the same command across multiple profiles simultaneously — querying two teams at once is a single invocation. This is useful for querying across environments (prod + staging) or regions.

Usage

Repeat the -p (or --profile) flag to target multiple profiles:

cx logs 'filter $m.severity == ERROR' -p prod -p staging
cx metrics query 'up' -p us-prod -p eu-prod

How it works

Each profile is resolved into an independent execution target with its own API client.
The command runs concurrently against all targets.
Results are merged into a single output, with each row tagged with a "profile" key identifying its source.
Errors from individual profiles are printed to stderr but do not fail the entire operation - successful results are still returned. The command exits 0 if at least one profile succeeds.

When a command has a result limit, the limit applies independently to each selected profile. For example, cx logs '<query>' -p prod -p staging --limit 100 can return up to 100 results from prod and up to 100 results from staging.

Result tagging

When multiple profiles are used, each result row includes an additional "profile" field:

{"profile": "prod", "timestamp": "...", "message": "..."}
{"profile": "staging", "timestamp": "...", "message": "..."}

When a single profile is used, no "profile" field is added.

Text output adds a Profile column to tables for REST commands (alerts, dashboards, metrics, rules, iam, notifications, etc.). DataPrime commands (logs, spans, dataprime query) prefix each rendered row with [<profile>].

Restrictions

--api-key and --region overrides are incompatible with multiple -p flags. These overrides apply to a single profile and would be ambiguous when targeting multiple profiles:

# This will error
cx logs 'filter $m.severity == ERROR' -p prod -p staging --api-key sk-...

Instead, store per-profile credentials ahead of time:

cx profiles add prod
cx profiles add staging

3.3 KiB Raw Permalink Blame History