Constraint CLI

Install, publish, and report governed Agent Skills with Constraint.

The package is named @constraint/cli; after installation, the terminal command is simply constraint.

Requirements

• Node.js 20 or newer
• A Constraint account with access to a WorkOS organization
• Codex, Claude Code, or both

Install

npm install --global @constraint/cli

Confirm the installation:

constraint --version
constraint --help

Sign in

constraint login

The CLI displays a verification URL and code, then uses WorkOS device authorization to sign in. It never asks for a Constraint API key or client secret.

Inspect or clear the current session:

constraint whoami
constraint logout

Configure agents

Run the interactive setup:

constraint setup

Or target agents explicitly:

constraint setup --agent codex --agent claude-code

Setup presents two separate stages: first it offers to add a marked Constraint block to each agent's global instructions, then it shows the global destination and installs the constraint-skills companion using the regular install-plan flow. Existing AGENTS.md and CLAUDE.md content outside that block is preserved.

Preview the instruction change without applying it:

constraint setup --agent codex --dry-run

Discover skills

constraint skills list
constraint skills list --search research
constraint skills domains
constraint skills inspect account-research
constraint skills inspect account-research --files

The server returns only skills the signed-in user is authorized to access. There is no domain-selection flag for reading or installing skills.

Install skills

Start the interactive installer:

constraint skills install account-research

Install for multiple agents in the current project:

constraint skills install account-research \
  --agent codex \
  --agent claude-code \
  --project

Install globally:

constraint skills install account-research --agent codex --global

Project installations write a portable skills-lock.json. Global installations use Constraint's private per-user configuration directory. The installer prefers managed links so agents can share one package; pass --copy to install independent copies. If links are unavailable, the installer falls back to copying and records the mode that actually occurred.

The installer stages changes, replaces managed paths atomically, and refuses to overwrite local edits.

List local installation records:

constraint skills list --installed --project
constraint skills list --installed --global

Update one skill or every skill in a scope:

constraint skills update account-research --project
constraint skills update --all --project
constraint skills update --all --global

Upload a skill

Create or edit a standard Agent Skill folder locally, then upload it:

constraint skills domains
constraint skills upload ./account-research --domain sales_pipeline

constraint skills domains --json returns the exact domain slugs where the authenticated user can upload skills. Agents should discover the destination first and pass one returned slug to --domain.

The folder must contain a root SKILL.md with name and description YAML frontmatter. Pass the owning domain with --domain; if it is omitted in an interactive terminal, the CLI asks which permitted domain owns the skill. Skill versions are immutable; uploading changed content creates the next version.

Report skill runs

The installed companion skill directs an agent to start a run after loading a governed skill:

constraint skills run start account-research \
  --client codex \
  --session <session-id>

The command prints a run ID. After completing the work, the agent uploads the real client transcript file for that run:

constraint skills run complete <run-id> <transcript-path>

The CLI uploads the transcript exactly as it exists on disk. It does not create a replacement transcript or modify the invoked skill.

Inspect completed runs:

constraint skills run list
constraint skills run list --skill account-research
constraint skills run list --team sales_pipeline --user <user-id>
constraint skills run get <run-id>
constraint skills run get <run-id> --raw --output transcript.jsonl

Team and user filters are enforced by Constraint's domain permissions.

Automation

Use --json for machine-readable output, --quiet to suppress normal output, and --yes to accept deterministic installer defaults. Non-interactive environments skip the terminal wizard.

constraint skills install account-research \
  --agent codex \
  --project \
  --yes \
  --json

Diagnostics

constraint doctor
constraint doctor --agent codex --agent claude-code

doctor reports API authentication and whether each agent has the companion skill and managed instruction block.

License

Constraint CLI is proprietary software. Use is permitted only under the Constraint CLI Proprietary License and any applicable agreement governing access to Constraint products and services.

Copyright (c) 2026 Constraint. All rights reserved.