Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command reference

The cjv command line includes built-in help for every subcommand; run cjv help or cjv <command> --help to inspect the options supported by your installed version. See Toolchains and versions for toolchain naming syntax and Project toolchains for the toolchain selection order.

Global options

OptionEffect
--jsonWrite structured JSON to stdout; unsupported by run, exec, init, and completion
--quiet, -qHide progress in every argument position; use component list --names-only for one name per line
--verboseEnable debug logs on stderr when CJV_LOG is unset; mutually exclusive with --quiet
--offlineDisable cjv network access and use local installations and cached files only
--config <path>Select the user settings.toml file; system fallback settings and project selection still apply
--no-auto-installDisable automatic installation of missing project requirements for this invocation
--help, -hShow command help
--version, -vShow the cjv version
+nameSelect an SDK before any subcommand that supports toolchain selection

An explicit --toolchain flag on a subcommand takes precedence over a leading global +name selector. Both exec and envsetup also accept +name after the subcommand name. run and exec forward all child arguments and preserve child exit codes.

Install, update, and uninstall

install

cjv install [toolchain]... [-t target]... [-c component]... [--allow-missing] [--allow-downgrade] [--reinstall]

install ensures the selected toolchain exists, preserving an installed release and adding requested targets or components. Use update to advance an installed channel. With no name it uses the active selection; multiple names are processed in order. -t and -c accept repeated flags or comma-separated lists:

cjv install lts sts
cjv install nightly -c stdx,docs

Installation and update policies

PolicyBehavior
DefaultPreserve required components and cross targets; missing artifacts block updates, while nightly searches published history for a compatible release
--allow-missingAllow unavailable optional components or targets to be skipped and removed, without reinstalling unchanged SDKs
Default installKeep the installed host release and add requested targets or components only
install --reinstallReinstall the existing release and retain selected components and targets to repair a damaged SDK
--allow-downgradeAllow nightly installation or update to select an older compatible nightly build

With no new components or targets, install for an installed toolchain can complete entirely offline. --force remains a deprecated compatibility flag for --allow-missing; install --no-update is retained because preserving the installed release is now the default. --allow-downgrade affects release resolution, without making ordinary install advance or downgrade an installed channel.

update

cjv update [toolchain]... [--allow-missing] [--allow-downgrade] [--no-self-update] [--dry-run]

cjv update updates the named toolchains. When called without names, it uses the global +name selector if present, or otherwise updates all installed tracked channels (lts, sts, nightly). Pinned concrete versions remain unchanged, and custom toolchains have no official update source. Only a full cjv update (without names or +name) checks for or installs cjv self-updates according to auto_self_update; pass --no-self-update to skip that check.

Channel updates stage the host SDK, tracked cross targets, and components before replacing the active installation atomically. Any failure preserves or restores the previous installation.

cjv update lts
cjv update --no-self-update

The first command updates lts only; the second updates all tracked channels while skipping the cjv self-update check.

--dry-run reports the newest release, the compatible release, and any blockers. A full update also reports the planned cjv self-check or self-update according to current policy. It never downloads archives, modifies installations, or writes caches. Use --json in CI. Explicitly naming a missing toolchain in update still installs it.

uninstall

cjv uninstall <toolchain>... [-y]

uninstall removes the SDK, owned cross SDKs, components, documentation, and directory overrides. Removing the default selects another installed host or clears the default. Interactive terminals prompt; non-interactive input or --json requires explicit -y (--yes). Output format does not authorize deletion. toolchain uninstall remains a hidden compatibility command.

check

cjv check

check queries SDK and cjv updates without installation or cache writes, using the same compatibility rules as update. A leading +name limits SDK inspection to that toolchain. Development builds skip their own version comparison. doctor checks local health; pin --check validates a concrete project selection, without checking for updates.

Update history and rollback

cjv toolchain history list [toolchain]
cjv toolchain history prune [toolchain] [--keep 2]
cjv toolchain rollback <toolchain> [snapshot]

Tracked updates save hosts, targets, and components as a group, retaining 2 snapshots. Listing/pruning without a name uses a leading +name, or all groups if no selector is provided. Omitting list remains a shorthand. --keep 0 clears snapshots without removing installations. Rollback verifies the chosen snapshot and saves the current group for undo. See Update history and rollback.

doctor and cache

cjv doctor
cjv cache dir
cjv cache list
cjv cache clean
cjv cache prune [--max-age 720h]

cjv doctor performs a read-only check of your configuration, proxy command entry points, and SDK metadata, exiting with a nonzero status code when it finds a problem. The cjv cache commands inspect and clean SHA-256-verified archives and manifests in <CJV_HOME>/cache/; cleaning the cache never removes installed SDKs. See Automation and JSON interfaces for JSON schemas and offline workflows.

Inspect toolchains

CommandPurpose
cjv, cjv showShow the same active toolchain, default host, and installation report, with the same JSON structure
cjv show activeShow the active toolchain and the selection rule that chose it
cjv toolchain listList hosts and cross targets, including actual releases and tracking, pinned, or custom kinds
cjv show homeShow the effective CJV_HOME data directory and its configuration source
cjv which [command] [--toolchain <tc>]Print the resolved path to an SDK tool binary, or the SDK root directory when [command] is omitted

Inspection commands do not install missing SDKs or components. show installed remains a hidden compatibility command for toolchain list.

toolchain list-remote

cjv toolchain list-remote [--channel all|lts|sts|nightly] [-t suffix] [--all-platforms] [--limit N]

Lists releases available in the remote distribution manifests. By default, it queries all channels for your current host platform. --all-platforms groups results across every platform, --limit 0 removes the per-group version limit, and -t (--target) filters releases by cross-target suffix.

Run commands and set the environment

run

cjv run [--install] <toolchain> <command> [args...]

Run any command using an explicitly named toolchain. Like exec, this prepares SDK paths and runtime libraries, installing missing requirements according to auto_install. --install explicitly enables installation, precedes the toolchain name, and conflicts with --no-auto-install:

cjv run --install sts cjc --version

exec

cjv exec [+toolchain] <command> [args...]

Runs a command with the active toolchain’s runtime environment (or selects a specific toolchain with +name). This is the recommended way to run compiled Cangjie binaries that dynamically link against SDK or stdx runtime libraries:

cjv exec ./my_binary
cjv exec +nightly ./my_binary

Use cjv exec -- +command if the executable name itself begins with +. Both run and exec forward child arguments and preserve exit codes.

envsetup

cjv envsetup [+toolchain] [--target=SUFFIX] [--shell=TYPE]

Prints a shell script that exports the SDK environment into your current shell session. Supported --shell formats are bash, fish, powershell, and cmd. Passing --target loads the environment of an installed cross SDK, and --json returns structured environment data.

Evaluate the printed script in the current shell to apply it. envsetup reads installed SDKs and validates project requirements; missing requirements produce explicit installation hints, without automatic installation. See Running commands and setting the environment for shell examples and project-based proxy selection.

Custom toolchains

cjv toolchain link <name> <directory>
cjv toolchain import <name> <archive|url> [--sha256 <hash>] [--replace] [--no-stdx]

link references an existing directory whose owner maintains its contents. import extracts a local archive or HTTP(S) URL into a managed installation. Its --sha256, --replace, and --no-stdx verify a digest, replace the named installation, and skip bundled stdx. Legacy archive/URL link forms remain compatible with a migration note and their old --force replacement flag. See Custom SDKs.

Cross-compilation targets

cjv target list [--toolchain <tc>] [--installed]
cjv target add <suffix>... [--toolchain <tc>]
cjv target remove <suffix>... [--toolchain <tc>]

Manages cross-compilation target SDKs attached to a host toolchain. target add installs target SDKs matching the host’s current release without upgrading the host; target remove removes the cross SDK and its target components while keeping the host installation. target list --installed works offline. See Cross-compilation.

Components

cjv component add <name>... [--toolchain <tc>] [--target <suffix>] [--reinstall]
cjv component link <name> <path> [--toolchain <tc>] [--target <suffix>] [--replace]
cjv component remove <name>... [--toolchain <tc>] [--target <suffix>]
cjv component list [--toolchain <tc>] [--target <suffix>] [--installed] [--names-only]

Manages optional components (stdx, docs, and stdx-docs), which can be passed as multiple arguments or comma-separated lists. Passing --target <suffix> targets an already-installed cross SDK on the selected host without installing the target itself.

component add --reinstall reinstalls a component; component link --replace replaces one. Old --force flags remain hidden compatibility options. list --names-only prints one name per line; -q always hides progress only. Only stdx supports directory links, with both dynamic/ and static/ present. External SDK directory links cannot be modified through component commands. See Components and offline documentation.

Offline documentation

cjv doc [topic] [--path] [--toolchain <tc>]

Opens local HTML documentation in your browser. Supported topics are std, dev-guide (alias book), tools, and stdx; omitting the topic opens the documentation home page. --path and --json print the resolved filesystem path without opening a browser. cjv docs is a command alias. Make sure the corresponding docs or stdx-docs component is installed first.

Selection and settings

pin

cjv pin [toolchain] [--check]

Writes cangjie-sdk.toml in the current directory with a resolved concrete release name while preserving existing components and targets. --check verifies that the project file pins a concrete release without writing to disk. See Automation and JSON interfaces.

default

cjv default [toolchain]

With no argument, display the global default; none clears it. Selecting a missing official SDK normally installs it first; --no-auto-install requires it to exist already. Failure leaves the previous selection intact. Cross SDKs cannot be defaults.

override

cjv override set <toolchain> [--path <dir>]
cjv override unset [--path <dir>] [--nonexistent]
cjv override list

Manages per-directory toolchain overrides, defaulting to the current working directory when --path is omitted. --nonexistent cleans up overrides for directories that no longer exist on disk. Overrides are stored in the active user settings file (default ~/.cjv/settings.toml) regardless of CJV_HOME. See Project toolchains and Configuration.

set

cjv set auto-self-update <enable|disable|check>
cjv set auto-install <true|false>
cjv set default-host <goos-goarch>
cjv set home <path>

Updates individual settings in the active user settings file (default ~/.cjv/settings.toml). See Configuration for defaults, system fallback inheritance, and environment variable overrides.

Initialization and self-management

init

cjv init [-y] [--default-toolchain <name>] [-c component]... [--no-modify-path]

Installs cjv and SDK proxy entry points into <CJV_HOME>/bin and configures PATH. By default, init queries the channels available for your current platform and selects the first available channel in the order lts, sts, then nightly. The interactive wizard lists only channels available for your platform; if no channel can be confirmed, initialization exits with an error.

OptionEffect
--default-toolchain <name>Select a default toolchain explicitly
--default-toolchain noneInstall cjv without installing an SDK
-c, --componentInstall components (stdx, docs, stdx-docs) alongside the initial SDK
-y, --yesSkip interactive prompts and accept defaults or explicit flags
--no-modify-pathLeave shell profiles and PATH unchanged

When standard input is not a terminal, init runs in non-interactive mode automatically. If installing the initial SDK fails, init exits with a nonzero status code while keeping the installed cjv binary, and prints ready-to-run retry and list-remote commands using the binary’s absolute path (so they work before PATH is reloaded in a new shell).

self update / self uninstall

cjv self update
cjv self uninstall [-y]

self update checks and updates cjv. self uninstall removes <CJV_HOME>, all toolchains, components, caches, snapshots, and PATH entries. Non-interactive input or --json requires explicit -y, matching SDK uninstall.

Shell completion

cjv completion <bash|zsh|fish|powershell>

Prints a tab-completion script for the specified shell. Run cjv completion <shell> --help for instructions on loading it in your shell profile.