AICodingKit CLI

The deployment CLI is authored in TypeScript and compiled to dist/. It consumes immutable Catalog entries, validates artifact SHA-256 values, and deploys verified project-level Agent adapters.

For complete installation, authentication, command, deployment, recovery, CI, and source development instructions, see the Chinese usage and development guide.

Print the installed CLI version with aicodingkit version, aicodingkit --version, or aicodingkit -v.

Agent Deployment

The CLI supports OpenCode, Claude Code, Cursor, CodeBuddy Code, and Trae. Select one or more Agent IDs during initialization. In an interactive terminal, bare init shows a Chinese multi-select prompt; automation must pass --agent. Multiple IDs use a comma-separated value and are deployed together:

aicodingkit init --agent opencode,claude-code,cursor,codebuddy,trae

Skills are installed in each Agent's native Skills directory. OpenCode, CodeBuddy Code, and Trae also receive native command wrappers. MCP entries use the Agent-native JSON shape, including shared .mcp.json ownership for Claude Code and CodeBuddy Code. Native JSONC configuration is changed only at managed MCP entries, preserving unrelated user content and comments.

aicodingkit init --agent <ids> on an existing project incrementally adds the requested Agents and deploys current selections. Remove an adapter deployment with:

aicodingkit uninstall --agent claude-code

Every selected Skill, MCP, Profile, Profile expansion, and Skill dependency must declare compatibility with every Agent enabled by the project. Historic Catalog entries that declare only cursor remain Cursor-only; compatibility is never inferred for an immutable historical release. New Packs declare spec.compatibility.agents, with an optional spec.overrides.<coordinate>.compatibility.agents item override.

search keeps every matching published version. Results are sorted by type, name, and semantic version descending; the highest version in the full Catalog has a [最新] marker. Descriptions are shown separately from coordinates in a compact Chinese result layout.

npm Release And Offline Artifact

Install the public CLI from npmjs with npm install --global @aicodingkit/cli. A protected GitLab release tag named v<package.json version> validates the source, creates an offline .tgz under the releases/ job artifact, and publishes the same version to npmjs. Configure NPM_TOKEN as a masked, protected, ordinary GitLab CI/CD variable in this project. It must be an npm access token allowed to publish the @aicodingkit scope; do not configure it as a File variable.

Published npm versions are immutable. Bump package.json, commit and push the change, then create and push the matching protected v<version> tag. The release job intentionally fails when npmjs reports that the version already exists.

Online GitLab Catalog

The CLI can read a private GitLab Catalog directly over HTTPS. It does not clone the Catalog or store access tokens in the project configuration. The optional init --catalog argument accepts a local Catalog directory or the normal GitLab project URL. The remote source is read through the GitLab Repository Files API.

Default Catalog Configuration

The CLI has a user-level configuration, so normal project initialization does not need to repeat the Catalog URL, branch, or Broker address. It never stores access tokens in this configuration. The built-in defaults are the company Catalog at https://git.iec.io/ai-coding-kit/aicodingkit-catalog, ref master, and the internal OAuth Broker at http://10.110.87.52:8080.

On Windows the configuration file is %APPDATA%\\aicodingkit\\config.json. On macOS it is ~/Library/Application Support/aicodingkit/config.json; on Linux it is ${XDG_CONFIG_HOME:-~/.config}/aicodingkit/config.json. Set AICODINGKIT_CONFIG to use a specific file, which is useful for a managed workstation image or a test environment.

aicodingkit config show
aicodingkit config set --catalog https://git.iec.io/ai-coding-kit/aicodingkit-catalog --catalog-ref master
aicodingkit init --agent cursor

init automatically creates the default user configuration on its first use. A per-project command line value always wins over the user default, including using a local Catalog for development:

aicodingkit init --agent cursor --catalog-ref release-candidate
aicodingkit init --agent cursor --catalog E:\work\aicodingkit-catalog

The final URL and ref used by each project are written to aicodingkit.jsonc, so later search, add, and install remain reproducible if the user default subsequently changes.

Online Authentication

OAuth Broker (recommended)

For normal developer workstations, use the AI Coding Kit OAuth Broker instead of distributing Catalog access tokens. The Broker completes GitLab authorization in the browser, enforces the user's GitLab access to the Catalog, and proxies only central Catalog artifacts. The CLI never receives a GitLab OAuth token, GitLab refresh token, Registry Deploy Token, or OAuth client secret.

aicodingkit login
aicodingkit auth status
aicodingkit init --agent cursor
aicodingkit search agent-constitution
aicodingkit add skill:[email protected]
aicodingkit logout

login records the Broker URL as the user default. On Windows, the Broker session is encrypted by DPAPI for the current Windows user before it is saved below %APPDATA%\aicodingkit\auth; no token environment variable is needed. AICODINGKIT_BROKER_TOKEN exists only for controlled automation and test environments and takes precedence over the saved session.

If an init, search, or install command accesses a Broker without a session, the CLI stops before creating aicodingkit.jsonc and reports the configured Broker URL plus the exact aicodingkit login --broker <url> command. HTTP authorization failures, network failures, and Broker 5xx responses have separate Chinese diagnostics; direct GitLab Catalog failures do not incorrectly suggest Broker login.

The Broker intentionally exposes only artifacts in the central Catalog project's Generic Package Registry. Historic entries that still point to another source Pack project remain available through the direct-token compatibility path below until they are migrated.

Direct GitLab token compatibility

Set a read-only GitLab access token before initializing or querying a private Catalog. New Pack versions publish their Artifact to the same central Catalog project Package Registry, so the CLI automatically reuses the Catalog read token for those Artifact downloads. No separate Artifact variable is required in that case.

$env:AICODINGKIT_CATALOG_READ_TOKEN = '<read-only Catalog token>'
$env:AICODINGKIT_CATALOG_READ_TOKEN_TYPE = 'gitlab-private-token'
aicodingkit init --agent cursor
aicodingkit search agent-constitution
aicodingkit add skill:[email protected]
aicodingkit status --check

Historic Catalog entries can still point to a source Pack project. For those entries only, configure an Artifact token that can read that source project's Generic Package Registry:

$env:AICODINGKIT_ARTIFACT_TOKEN = '<read-only legacy Package token>'
$env:AICODINGKIT_ARTIFACT_TOKEN_TYPE = 'gitlab-private-token'

The Catalog token types are bearer, gitlab-private-token, and gitlab-job-token. The default for AICODINGKIT_CATALOG_READ_TOKEN_TYPE is gitlab-private-token; an explicitly supplied Artifact token keeps its existing default of bearer. The CLI writes the remote project URL, ref, resolved entries, and their index digest to the project state, but never writes either token.