Upload local rules to the CodeCharter portal with push

How to upload locally developed .ccr rules to the portal and version them there using codecharter push.

Updated on 2026-09-01

When you develop rules locally — for example with the VS Code extension or directly in a text editor — you can upload them to the portal with codecharter push. The command scans a directory for .ccr files, uploads them as rule drafts, and creates a profile draft in the portal without touching the currently published version. If a rule or the profile already has an open draft in the portal, the push stops with a conflict instead of overwriting it.

Prerequisites

You need:

A CodeCharter CLI that includes the push command — run codecharter --version to check. If you need to upgrade, see Downloads.
A way to authenticate against the portal: either an installed codecharter.license (the default case, no extra option needed) or an API key with the write:rules scope, passed via the --api-key option (you can keep the key in an environment variable and pass it on the command line, as in the examples below)
One .ccr file per rule, optionally a .spec.md file with the same base name next to it

Directory layout

codecharter push operates on a directory and scans it recursively for .ccr files:

rules/
  no-async-void.ccr
  no-async-void.spec.md
  max-method-length.ccr

Canonical usage

codecharter push ./rules \
  --profile my-team-rules \
  --version 1.0.0 \
  --portal-url https://codecharter.tools \
  --api-key $CODECHARTER_API_KEY

This scans ./rules recursively for .ccr files. Each rule's slug is derived from the filename (without the .ccr extension), so no-async-void.ccr becomes the slug no-async-void. A sibling .spec.md with the same base name is uploaded automatically. The run creates the profile draft my-team-rules@1.0.0 from those rules; if the profile already has an open draft, the push fails with a conflict so it cannot overwrite work in progress.

--portal-url and --api-key are only shown here for illustration: --portal-url defaults to the hosted portal when omitted, and --api-key defaults to the installed codecharter.license when omitted.

On success the CLI prints a summary line you can verify against:

Pushed 2 of 2 rule(s); profile draft 'my-team-rules@1.0.0' created.

The rule file needs no declaration block: the slug comes from the filename, and the severity comes from the @severity directive inside the rule file (default: warn if the directive is absent). codecharter push uploads the file content as-is; the directive takes effect when the rule is loaded.

Dry run

codecharter push ./rules \
  --profile my-team-rules \
  --version 1.0.0 \
  --portal-url https://codecharter.tools \
  --api-key $CODECHARTER_API_KEY \
  --dry-run

--dry-run lists the rules and the profile draft that would be pushed, without uploading anything. Useful to verify the plan before opening real drafts.

Options

Option	Required	Description
`--profile <slug>`	yes	The profile slug to create or update.
`--version <semver>`	yes	The semantic version for the profile draft (e.g. `1.0.0`).
`--portal-url <url>`	no	URL of the CodeCharter portal. Defaults to the hosted portal; pass this only for a self-hosted portal.
`--api-key <key>`	no	API key used to authenticate against the portal (needs the `write:rules` scope). Defaults to the installed license when omitted.
`--license <path>`	no	Path to a `codecharter.license` file. Overrides search-path discovery.
`--dry-run`	no	Show planned actions without uploading.

Exit codes

Code	Meaning
`0`	All drafts created successfully (or dry run completed).
`1`	A rule or the profile already has a conflicting draft.
`2`	Usage error, I/O error, or network error.

After the push

After a successful push the rule appears in the portal under /rules with the Draft badge. From there you can:

run the spec in the portal (Run specs)
publish a new version (Publish)

A push never publishes on its own — that remains a deliberate manual step in the portal.

If a pushed rule has no published version yet, the profile draft references the rule draft and the CLI warns:

warning: rule 'no-async-void' has no published version yet; profile references the draft.

Common errors

Conflicting draft

error: Rule 'no-async-void' already has a draft. Discard or publish it first.

error: Profile 'my-team-rules' already has a draft. Discard or publish it first.

A rule or the profile already has an open draft in the portal. Discard or publish that draft in the portal, then push again. The command exits with code 1.

No portal credential available

error: no portal credential available. Pass --api-key, set CODECHARTER_API_KEY, or install a codecharter.license (point at it with --license).

Neither an API key nor a valid installed license is available. Pass an API key with --api-key, set the CODECHARTER_API_KEY environment variable, or install a codecharter.license (point at a non-default location with --license). The command exits with code 2.

No rule files found

error: no rule files (.ccr) found in './rules'.

The directory does not contain any supported rule files (.ccr, or the legacy .cgr; the scan is recursive). Check the path you passed. The command exits with code 2.

Portal rejects the request

error: portal returned 401 Unauthorized for rule 'no-async-void'.

The portal refused the upload. Check that the API key or installed license you used is valid and not expired, and that --portal-url points to the right portal. The command exits with code 2.