Orb create fails with "this name is invalid" on CircleCI CLI preview (v1.x)

Overview

When creating an orb with the CircleCI CLI **preview** release (`1.0.x-pre`), the following command may fail even though the orb name is valid:

circleci orb create <namespace>/<orb-name> --private

Example error:

API returned 400: Cannot create an Orb named '<namespace>/<orb-name>': this name is invalid.
See the documentation for more information about the restrictions on Orb names.

The same failure can occur for public orbs (without --private).

This article covers:

Why the error appears for a correctly formatted command
How to work around it by using the stable CLI (`0.1.x`) or the API
Notes about `circleci orb init` on older preview builds

Affected: CircleCI CLI preview `1.0.x-pre`

Not affected: CircleCI CLI stable `0.1.x`

Root Cause

The CLI command format circleci orb create <namespace>/<orb-name> is correct. The `/` separates the namespace from the orb name; it is not part of the orb name itself.

Orb names must match this pattern:

Start with a lowercase letter (a–z)
Contain only lowercase letters, digits (0–9), hyphens (-), and underscores (_)

Valid orb names include values such as common, my-orb, and s3_cache.

On the stable CLI (0.1.x), create sends only the orb name (for example, <orb-name>) to the create API, with the namespace provided separately.

On the preview CLI (1.0.x-pre), create incorrectly sends the full slug (<namespace>/<orb-name>) as the orb name. Because "/" is not allowed in an orb name, the API returns "400" with “this name is invalid.”

Separately, some preview builds do not include circleci orb init yet. That command was added in a later preview release; its absence is unrelated to the create naming failure, but it can block the documented Orb Development Kit flow on those builds.

Solution

Option 1 (recommended): Use the stable CLI (0.1.x)

Windows (WinGet)

# Remove the preview CLI
winget uninstall --id CircleCI.CLI.Preview
# Install the stable CLI
winget install --id CircleCI.CLI
# Confirm the version is 0.1.x (not 1.0.x-pre)
circleci version

macOS (Homebrew)

brew uninstall circleci
brew install circleci
circleci version

Linux (Snap)

sudo snap install circleci
circleci version

Then create the orb:

circleci orb create <namespace>/<orb-name> --private

Publish a version after the orb exists:

circleci orb publish <path-to-orb.yml> <namespace>/<orb-name>@dev:first

Option 2: Create the orb via the API

Use this if you need to stay on the preview CLI for other work. You need a [Personal API token](https://app.circleci.com/settings/user/tokens).

Important: In the create request, name must be only <orb-name>, not <namespace>/<orb-name>.

1. Look up the namespace ID:

curl -s -X POST https://circleci.com/graphql-unstable \
  -H "Content-Type: application/json" \
-H "Circle-Token: <YOUR_TOKEN>" \
  -d '{
"query": "query($name: String!) { registryNamespace(name: $name) { id } }",
"variables": { "name": "<namespace>" }
  }'

Use the returned registryNamespace.id as <NAMESPACE_UUID>.

2. Create the orb (private example):

curl -s -X POST https://circleci.com/api/v3/orb/packages \
  -H "Content-Type: application/json" \
-H "Circle-Token: <YOUR_TOKEN>" \
  -d '{
"data": {
"attributes": {
"name": "<orb-name>",
"is_private": true
      },
"references": {
"namespace": { "id": "<NAMESPACE_UUID>" }
      }
    }
  }'

For a public orb, set "is_private": false.

3. Publish a version with the stable CLI, or via GraphQL:

circleci orb publish <path-to-orb.yml> <namespace>/<orb-name>@dev:first

Or:

curl -s -X POST https://circleci.com/graphql-unstable \
  -H "Content-Type: application/json" \
-H "Circle-Token: <YOUR_TOKEN>" \
  -d '{
"query": "mutation($config: String!, $orbName: String, $namespaceName: String, $version: String!) { publishOrb(orbName: $orbName, namespaceName: $namespaceName, orbYaml: $config, version: $version) { orb { version } errors { message } } }",
"variables": {
"config": "<ORB_YAML_STRING>",
"orbName": "<orb-name>",
"namespaceName": "<namespace>",
"version": "dev:first"
    }
  }'

Replace <ORB_YAML_STRING> with the full contents of your packed orb YAML (JSON-escaped string).

Verification

circleci version shows 0.1.x when using Option 1
circleci orb create <namespace>/<orb-name> succeeds (or the API create returns 201)
The orb appears under the organization’s Orbs settings page

Additional notes

Once created, an orb name cannot be deleted or renamed. Choose `<orb-name>` carefully.
The documented create syntax remains circleci orb create <namespace>/<orb-name>. Customers do not need to change how they write the command when using the stable CLI.
If circleci orb init is missing from a preview install, use the stable CLI or follow the [manual orb authoring process](https://circleci.com/docs/orbs/author/manual-orb-authoring-process/).