CircleCI-Public / CircleCI-Public/circleci-cli

orb and config commands 404 against CircleCI Server on v1 CLI: they target /api/v3, which Server does not implement

Open
#1,775 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Go
Stars
459
Forks
255
Avg merge
1d 4h
Merged PRs (30d)
59

Description

### Description

On the v1 CLI, `orb` and `config` commands talk to `/api/v3`. CircleCI Server does not implement `/api/v3`,
so those commands fail with `Not Found` against a self-hosted Server instance. The v0.1 CLI worked because it
used `/graphql-unstable`, which Server does implement.

This looks like a regression rather than an intentional scope change, since Server support is still advertised
in two places:

- the [README](https://github.com/CircleCI-Public/circleci-cli/blob/3bc297635b4d9ff9060f13d6b6ff437e660cccde/README.md#L23):
*"The CLI is supported for users on circleci.com and CircleCI server; with support for macOS, Windows, and Linux."*
- `circleci setting set --help`, in its own examples: *"Point to a self-hosted CircleCI server:
`circleci setting set host https://circleci.mycompany.com`"*

### Environment

| | |
|---|---|
| CLI (broken) | `1.0.48692` — linux/amd64 |
| CLI (working) | `0.1.47860` — linux/amd64 |
| Server | CircleCI Server **4.10.0** (`GET /version` → `4.10.0`) |

The instance host is shown below as `https://circleci.example.com`.

### Reproduction

`orb list`:

```console
$ CIRCLE_HOST=https://circleci.example.com CIRCLE_TOKEN= circleci orb list --debug
DEBU GET /api/v3/orb/packages http.request.method=GET http.response.status_code=404 duration=232ms \
url.full="https://circleci.example.com/api/v3/orb/packages?filter%5Bcertified%5D=true" kind=client
error: Orb API request failed for "".
API: {"message":"Not Found"}
```

`config validate`:

```console
$ CIRCLE_HOST=https://circleci.example.com CIRCLE_TOKEN= circleci config validate .circleci/config.yml --debug
DEBU POST /api/v3/configs/compile http.request.method=POST http.response.status_code=404 duration=124ms \
url.full=https://circleci.example.com/api/v3/configs/compile kind=client
error: Config API request failed%!(EXTRA string=)
API: {"message":"Not Found"}
```

The 404 does not depend on the credential: `orb list` produces exactly the output above both with a valid Server
API token and with a deliberately invalid one. Server answers `401` for endpoints that exist but reject the
credential, so a `404` here is a routing failure — see below.

### This is a missing endpoint, not an auth problem

Unauthenticated probes of the same Server instance separate the two cases cleanly, since Server returns `401` for
endpoints that exist but require auth:

| Endpoint | Status |
|---|---|
| `GET /api/v3/orb/packages` | **404** `{"message":"Not Found"}` |
| `GET /api/v3/orb/versions` | **404** `{"message":"Not Found"}` |
| `POST /api/v3/configs/compile` | **404** `{"message":"Not Found"}` |
| `GET /api/v2/me` | 401 `{"message":"You must log in first."}` |
| `GET /api/v1.1/me` | 401 |
| `POST /graphql-unstable` | 401 |

So `/api/v2`, `/api/v1.1` and `/graphql-unstable` are all present and merely protected, while the entire `/api/v3`
surface is absent.

Corroborating this from the server side: the instance's own `GET /api/v2/openapi.json` (publicly readable) lists
44 paths and contains **no orb-registry endpoints** at all — the only orb-related path is
`/organization/{org}/url-orb-allow-list`. On Server, orb registry data appears to be reachable only over GraphQL.

### What changed between the two CLIs

String counts in the two release binaries:

| Symbol | `0.1.47860` | `1.0.48692` |
|---|---|---|
| `graphql-unstable` | 1 | **0** |
| `CIRCLECI_CLI_HOST` | 1 | **0** |
| `/api/v3` | 3 | **29** |

The GraphQL client that made these commands work on Server is gone.

### Expected behaviour

Either of these would resolve it:

1. Orb and config commands work against Server again — e.g. by falling back to `/graphql-unstable` when the
configured host is not `circleci.com`, or by gating on a capability/version probe.
2. If Server support has been intentionally dropped for these commands, say so in the README and in
`setting set host --help`, and emit an actionable error (e.g. *"orb commands are not supported on CircleCI
Server; use CLI v0.1.x"*) instead of a bare `Not Found`.

Option 1 is much preferable from a Server user's perspective: `circleci config validate` in particular is the
main reason to have the CLI installed at all, and there is currently no v1 path to it on Server.

### Minor, but adjacent

Two error-formatting bugs visible in the output above:

- `Config API request failed%!(EXTRA string=)` — a format string with no verb receiving an extra argument.
- `Orb API request failed for ""` — the identifier interpolated into the message is empty, so the error names
nothing useful.

### Workaround

Use the last v0.1 release, which still has a real `--host` flag and `CIRCLECI_CLI_HOST`, and which routes these
commands to `/graphql-unstable` — an endpoint the Server instance does serve:

```console
$ CIRCLECI_CLI_TOKEN= circleci orb list --host https://circleci.example.com # 0.1.47860
```

(With a deliberately invalid token this returns `401` from `/graphql-unstable`, rather than v1's `404` — i.e. it
reaches a real endpoint.)

Note also that v0.1's `--host` flag no longer exists on v1 — it is rejected exactly like an unknown flag, which
makes the transition confusing to diagnose. On v1 the host is `circleci setting set host ` or `CIRCLE_HOST`.
Both forms were used for the reproductions above.

Contributor guide

Open the contributing guide

Research direction

Start from the orb and config command entry points and trace their requests to /api/v3, then compare the v0.1 CLI's /graphql-unstable path and host handling. Reproduce the 404s against CircleCI Server and make the commands work through a supported endpoint, or provide the documented actionable unsupported-feature error; verify the adjacent error messages as well.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, graphql
Domain
api, cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.