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

cjv user guide

Warning

cjv is now in maintenance mode. No new features will be developed; future changes will be limited to security fixes.

You can continue using cjv, but it may or may not work as expected.

cjv is a version manager for the Cangjie SDK. It installs multiple toolchains on your machine and selects a version for each project. Once the command path is configured, commands such as cjc and cjpm use cjv to invoke the selected SDK.

Get started

Start with installation, then follow the quick start to check your toolchain, configure a project, and run commands.

The installation wizard queries channels available for your platform. cjv’s platform support may differ from the SDK’s release coverage. Use cjv toolchain list-remote to check available versions.

Configure projects and manage SDKs

Toolchains and versions explains channels, pinned versions, and name syntax. Commit a cangjie-sdk.toml in a team project to share version, component, and target SDK requirements.

See components for extension libraries and offline documentation, and cross-compilation for target SDKs. Existing SDK directories and archives can be registered as custom toolchains.

For running compiled programs or setting up your current shell, see running commands and setting the environment.

Configuration and reference

Configuration and environment variables cover user settings and temporary overrides. Use network proxies when upstream access requires a proxy. See enterprise and offline deployment for internal sources, managed clients, and fully offline installation.

Use the command reference for command options and common questions for troubleshooting.

See Automation and JSON interfaces for version pinning checks, CI isolation, offline caches, rollback, and JSON output. For development, see the developer guide.

Install cjv

cjv is a standalone executable and does not require an existing Cangjie SDK. After installation, cjv and proxies for SDK tools such as cjc and cjpm reside in <CJV_HOME>/bin, which defaults to ~/.cjv/bin on Unix and %USERPROFILE%\.cjv\bin on Windows.

Installing via the installer scripts

Installer scripts are available for Linux, macOS, Windows, and HarmonyOS HiShell.

On Linux, macOS, or HarmonyOS HiShell:

curl -sSf https://cjv.zxilly.com/install.sh | sh

On Windows PowerShell:

irm https://cjv.zxilly.com/install.ps1 | iex

The script detects your operating system and CPU architecture, downloads and verifies the cjv binary against its SHA-256 checksum, and then runs cjv init. In an interactive terminal, cjv init launches a setup wizard; when standard input is not a terminal, it proceeds with sensible defaults.

Passing arguments for automated or non-interactive installs

Both installer scripts accept options that allow you to customize the installation without interactive prompts. For example, in a CI pipeline where you want to install cjv first and let the project’s cangjie-sdk.toml select the SDK later, pass -y and --default-toolchain none:

curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- -y --default-toolchain none
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Yes -DefaultToolchain none

The Unix install.sh script handles --mirror and --version itself and forwards all remaining arguments directly to cjv init. The PowerShell install.ps1 script exposes matching parameters: -Mirror, -Version, -Yes, -DefaultToolchain, and -NoModifyPath. See the init section of the Command reference for the full list of cjv init flags.

Pinning the cjv version

If you want repeatable automated builds, you can pin the exact cjv release tag (including prereleases) that the installer downloads:

curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- --version v0.4.1 -y --default-toolchain none
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Version v0.4.1 -Yes -DefaultToolchain none

Replace v0.4.1 with the release tag you need. Both scripts also honor the CJV_VERSION environment variable, though an explicit --version or -Version flag on the command line takes precedence. When neither is specified, the installer fetches the latest stable release.

--version / CJV_VERSION selects the version of the cjv manager itself, whereas --default-toolchain / -DefaultToolchain independently selects which Cangjie SDK toolchain to install. Explicit download root overrides (CJV_UPDATE_ROOT, CJV_GITHUB_ROOT, and CJV_GITCODE_ROOT) take precedence over version selection—if you point cjv at an internal artifact server, point the URL directly at the desired version’s release directory.

How cjv init selects an initial SDK

By default, cjv init queries the upstream manifest for channels that publish builds for your current host platform, and picks the first available channel in the order lts, sts, and nightly. You can override this choice with --default-toolchain <name>, or skip installing an SDK altogether with --default-toolchain none.

If downloading or extracting the initial SDK fails—for example, due to a transient network error—cjv init exits with a nonzero status code while keeping the cjv binary itself installed. The error output includes a ready-to-run retry command (using the absolute path to cjv so it works before you reload your shell) or you can inspect available releases with cjv toolchain list-remote.

Using the GitCode mirror

If GitHub access is slow or unreliable from your network, pass --mirror (or -Mirror in PowerShell) to install the mirror build of cjv:

curl -sSf https://cjv.zxilly.com/install.sh | sh -s -- --mirror
& ([scriptblock]::Create((irm https://cjv.zxilly.com/install.ps1))) -Mirror

The mirror build uses GitCode by default for both the Cangjie version manifests and cjv self update. If your organization hosts an internal mirror, see Enterprise and offline deployment.

Manual installation from release archives

If you prefer not to pipe a script into your shell, you can download a release archive directly from GitHub Releases, extract cjv (or cjv.exe on Windows) into a directory on your PATH, and run cjv init:

PlatformRelease archive
Linux x86_64cjv_linux_amd64.tar.gz
Linux ARM64cjv_linux_arm64.tar.gz
macOS Apple Siliconcjv_darwin_arm64.tar.gz
macOS Intelcjv_darwin_amd64.tar.gz
Windows x86_64cjv_windows_amd64.zip
HarmonyOS x86_64cjv_openharmony_amd64.tar.gz
HarmonyOS ARM64cjv_openharmony_arm64.tar.gz

GitCode Releases publishes equivalent mirror archives prefixed with cjv-mirror_. In addition, the download page at https://cjv.zxilly.com provides standalone cjv-init (and cjv-init.exe) binaries that launch the setup wizard directly when executed.

Installing from source with Go

If you have a Go toolchain installed that satisfies the repository’s go.mod requirement, you can build and install cjv directly from source:

go install github.com/Zxilly/cjv/cmd/cjv@latest
cjv init

go install places the compiled binary in GOBIN (or $(go env GOPATH)/bin if GOBIN is unset). Make sure that directory is in your PATH, or let cjv init copy the managed binary into <CJV_HOME>/bin. For custom build tags and cross-compiling cjv, see Build from source in the Developer Guide.

PATH configuration and verification

All SDK proxy binaries (cjc, cjpm, etc.) live in <CJV_HOME>/bin, which defaults to ~/.cjv/bin. Running cjv init adds this directory to your PATH automatically—updating the user PATH in the registry on Windows, or appending to your shell profile on Unix. Even if you skip cjv init and run cjv install directly, the first toolchain installation will also ensure <CJV_HOME>/bin is added to your PATH.

Once installation completes, open a new terminal window so your shell reloads PATH, and verify that cjv is available:

cjv --version

If you prefer to manage your shell profiles manually, pass --no-modify-path to cjv init (or -NoModifyPath to install.ps1), or set the environment variable CJV_NO_PATH_SETUP=1.

Next, head over to the Quick start chapter to select a toolchain and compile your first project.

Quick start

After installing cjv, check the selected toolchain, set a default version, configure a project version, and manage updates.

Checking your installation

After completing the setup wizard, open a new terminal so your updated PATH is loaded, and check the active toolchain:

cjv show
cjc --version

cjv show displays your default host platform, all installed toolchains, and which toolchain is currently active. If your shell reports that cjc cannot be found, double-check that <CJV_HOME>/bin (by default ~/.cjv/bin) is on your PATH—see PATH configuration and verification for details.

Choosing a default toolchain

If you installed cjv with --default-toolchain none (or skipped SDK installation during setup), you can query the releases available on a channel and set a global default toolchain. Let’s take the lts channel as an example:

cjv toolchain list-remote --channel lts
cjv default lts
cjc --version

If the toolchain you pass to cjv default is not installed yet, cjv downloads and installs it automatically before saving it as the default. If lts does not publish an SDK for your platform yet, run cjv toolchain list-remote for sts or nightly and select that channel instead—or run cjv init again to let the interactive wizard pick an available channel for you.

The global default toolchain is used whenever you are in a directory that does not have a project toolchain file or a local directory override. To see which toolchain is active in your current directory and why it was chosen, run:

cjv show active

See Toolchains and versions for a full explanation of channels and version naming.

Choosing a version for a project

Using cangjie-sdk.toml

In a team repository, you usually want every contributor and CI runner to build with the exact same Cangjie release and extension libraries. You can declare these requirements in a cangjie-sdk.toml file at the root of your project:

[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]

Replace lts-1.0.5 with a version that your project needs and your distribution source provides (or run cjv pin lts to generate the file with the resolved version automatically).

Whenever you run cjpm build or cjc inside that project directory, cjv automatically selects the toolchain declared in cangjie-sdk.toml. By default, auto_install is enabled, so cjv will download and install any missing SDK, component, or cross-compilation target on the fly. Running a proxy command will never unexpectedly upgrade an SDK that is already installed.

Setting a local directory override

If you want to test a project with a different toolchain on your own machine without modifying cangjie-sdk.toml, you can set a directory override:

cjv override set sts
cjv show active
cjv override unset

Directory overrides are stored in your personal ~/.cjv/settings.toml file rather than inside the project directory, while cangjie-sdk.toml is meant to be committed to version control. See Project toolchains for how overrides and project files interact.

Running a command with another version

Sometimes you just want to run a single command with a specific toolchain without changing your default or directory settings. Use cjv exec:

cjv exec +sts cjc --version

exec runs SDK tools or compiled programs with SDK and runtime library paths, installing missing requirements according to auto_install. cjv run sts cjc --version remains the explicit-toolchain compatibility form.

If you have compiled your own Cangjie binary and need to run it with the dynamic libraries from the SDK or stdx, use cjv exec:

cjv exec ./my_binary

See Running commands and setting the environment for more on run, exec, and envsetup.

Inspecting installed toolchains

Here are the most common commands for inspecting your local setup:

cjv show active
cjv which cjc
cjv toolchain list
  • cjv show active prints the currently selected toolchain and the rule that selected it (such as a cangjie-sdk.toml file, a directory override, or the global default).
  • cjv which cjc prints the full filesystem path to the cjc executable inside the active SDK.
  • cjv toolchain list lists hosts and cross SDKs with installation names, actual releases, and tracking/pinned/custom kinds. show installed remains a hidden compatibility command.

Keeping toolchains and cjv up to date

Updating tracked channels

When new versions of the Cangjie SDK are released, you can check for available updates or install them across all of your tracked channels (lts, sts, nightly):

cjv check
cjv update

cjv check queries the remote manifest and reports available updates for your installed SDKs and for cjv itself without installing anything. cjv update downloads and installs updates for all tracked channels, while leaving pinned versions (like lts-1.0.5) and custom toolchains untouched.

Whether a full cjv update also checks for or installs updates to cjv itself is controlled by the auto_self_update setting (check by default). You can also update cjv manually at any time by running:

cjv self update

Uninstalling a toolchain

To remove an installed toolchain that you no longer need and reclaim disk space:

cjv uninstall sts

Uninstalling a host toolchain also removes its attached components, cross-compilation targets, and offline documentation. For a complete list of commands and flags, see the Command reference.

Running commands and setting the environment

The cjc, cjpm, and other executables in <CJV_HOME>/bin are proxies for SDK tools. Each proxy selects an SDK using the project toolchain rules, prepares environment variables and library paths, and forwards command-line arguments and the child process exit code.

Running SDK tools and compiled programs

In addition to calling proxy binaries like cjc directly, cjv provides two subcommands—cjv run and cjv exec—for running commands in an isolated child process environment:

cjc --version
cjv exec +sts cjc --version
cjv exec ./my_binary arg1 arg2
cjv exec +nightly ./my_binary

Understanding the difference between run and exec makes it easy to pick the right tool:

  • cjv run [--install] <toolchain> <command> [args...] retains the explicit positional toolchain form and runs any program. It shares the runtime environment and auto_install policy with exec. --install explicitly enables installation, --install=false disables it, and enabling it conflicts with --no-auto-install.
  • cjv exec [+toolchain] <command> [args...] is the recommended entry point, using the project selection or an explicit toolchain, setting SDK and runtime library paths, and installing missing requirements according to auto_install. An explicit toolchain replaces project selection; project components and targets apply when using the project selection.

Both run and exec modify the environment for the spawned child process only, and both forward stdin, stdout, stderr, and the child’s exit code directly.

If you need to run a command whose executable name literally begins with a + character, pass -- before the command name so cjv exec does not interpret it as a +toolchain selector:

cjv exec -- +command

which reads a tool path (or the SDK root with no command), without installation or requiring unrelated project components or targets.

Configuring the current shell with envsetup

cjv envsetup prints a script that loads SDK paths and environment variables into the current shell. Use it with external build systems, Makefiles, or CMake scripts that need the SDK environment:

# Bash or Zsh
eval "$(cjv envsetup)"
# Fish
cjv envsetup | source
# Windows PowerShell
cjv envsetup | Invoke-Expression

You can pass +nightly (or any installed toolchain name) to cjv envsetup +nightly to load a specific toolchain rather than the active selection, or pass --shell=bash|fish|powershell|cmd to choose the output syntax explicitly. When --shell is omitted, cjv detects your current shell automatically; if detection fails, it prints a notice to stderr and falls back to POSIX shell syntax.

For automation tools and IDE integrations, you can also run cjv --json envsetup to get the resolved environment variables as structured JSON; see Automation and JSON interfaces for details.

envsetup reads installed SDKs and validates declared project components and targets. Missing requirements produce explicit installation hints without automatic installation. It accepts at most one valid +toolchain positional argument.

Environment variables configured by cjv

Whether you run a command via a proxy, cjv run, cjv exec, or cjv envsetup, cjv configures the following variables for the selected SDK:

  • CANGJIE_HOME — Points to the root directory of the selected SDK installation.
  • PATH — Prepends the SDK’s compiler and tool directories so that internal tools resolve directly to that SDK.
  • Dynamic library search paths — Configures runtime library paths according to the host operating system: LD_LIBRARY_PATH on Linux and HarmonyOS, DYLD_LIBRARY_PATH on macOS, and PATH on Windows.
  • stdx library paths — When the stdx component is installed for the selected toolchain, cjv automatically sets CANGJIE_STDX_PATH_DYNAMIC and CANGJIE_STDX_PATH_STATIC to point to the component’s dynamic/ and static/ directories.

Switching projects after envsetup

Keep in mind that once you evaluate cjv envsetup in a terminal, your current shell session’s PATH points directly to that specific SDK’s bin directory ahead of <CJV_HOME>/bin. As a result, cd-ing into another project with a different cangjie-sdk.toml will not switch compilers in that terminal session.

To return to automatic per-project proxy selection, open a new terminal window—or evaluate cjv envsetup again in the new directory to switch the active session.

Loading a cross-compilation SDK environment

When cross-compiling for another platform, you can use cjv envsetup with the --target flag to load the paths and libraries of an installed cross SDK:

cjv install sts --target ohos
eval "$(cjv envsetup +sts --target=ohos)"

--target selects the installed cross SDK whose release matches the selected host toolchain. Note that envsetup --target does not install a missing target automatically, nor does it provide an emulator to execute binaries built for another operating system or CPU architecture.

Consult the official Cangjie SDK documentation for the compiler flags and target linker requirements of your target platform, and see the Cross-compilation chapter for how to install and manage target SDKs with cjv.

Toolchains and versions

A toolchain is one Cangjie SDK installation containing the compiler (cjc), package manager (cjpm), build tools, and runtime libraries. cjv stores toolchains under <CJV_HOME>/toolchains/ and optional components (stdx and offline documentation) in separate directories.

cjv supports several kinds of toolchains. The most common track the official release channels—lts, sts, and nightly—but cjv can also install specific pinned versions from the release manifests, toolchains for alternate host platforms, and custom toolchains from local directories or archives.

Channels and names

Standard release channel and version toolchain names follow this form:

[<channel>-]<version>[-<host>]
<channel>[-<date>][-<host>]

<channel>       = lts|sts|nightly
<version>       = <major.minor>|<major.minor.patch>|<nightly-version>
<date>          = YYYY-MM-DD
<host>          = <os>-<arch>

Here is how the different toolchain selectors work in practice:

NameMeaning
ltsTrack the Long-Term Support release channel
stsTrack the Short-Term Support release channel
nightlyTrack development builds published in the nightly manifest
lts-1.0.5Pin a specific version within a channel
1.0.5Omit the channel prefix and let cjv find the matching release
sts-1.2, 1.2Select the latest stable patch within that minor version series
nightly-2026-10-04Select the latest published nightly build for that date
my-sdkA custom toolchain registered with cjv toolchain link

The version numbers and dates in the table above illustrate the naming syntax. To see which versions are actually published by your distribution source for your platform, run cjv toolchain list-remote:

cjv toolchain list-remote --channel lts
cjv toolchain list-remote --channel nightly --limit 10

Official channel names are case-insensitive. Toolchain names that do not match an official channel or version pattern can be used to name custom toolchains—provided they do not conflict with official names, contain path separators, begin with +, or equal ., .., or an empty string.

Tracked channels and pinned versions

When you install a channel name like lts and a specific version like lts-1.0.5, cjv treats them as two completely independent installations:

cjv install lts
cjv install lts-1.0.5

When you later run cjv update lts (or cjv update), cjv updates the tracked lts installation to the newest release on that channel, while leaving lts-1.0.5 untouched. Their attached components and cross-compilation targets are also managed independently. Running proxy commands like cjc always uses the release currently installed on disk; upgrading an installed toolchain requires explicit cjv update, while install preserves the installed release.

toolchain list displays installation identity, actual release, and kind. For example, lts → lts-1.0.5 is tracking while an independent lts-1.0.5 is pinned; identical releases can have different update lifecycles.

Shorthand selectors—such as a minor version (sts-1.2) or a nightly date (nightly-2026-10-04)—are resolved against the manifest at installation time and installed as concrete pinned versions. When you want a team project to build with the exact same compiler across machines, write the full concrete release name in cangjie-sdk.toml (or run cjv pin to resolve and write it for you).

Nightly availability and component compatibility

Nightly builds are published frequently, and occasionally a newest nightly build may not yet include every optional component (stdx, docs) or cross-compilation target SDK.

When you first install or explicitly update the nightly channel, cjv checks which components and cross targets are required (either requested on the command line or already installed on your local nightly toolchain) and automatically searches the published history in nightly.json for the newest compatible release. By default, cjv will not downgrade an already-installed nightly toolchain to an older build; if you want to permit stepping back to an older compatible nightly, pass --allow-downgrade. See Installation and update policies in the Command reference for full details.

Host platforms

You can optionally append a host platform suffix to a toolchain name, such as sts-linux-x64 or sts-1.2.0-darwin-arm64. Each host platform is installed separately. Specifying your machine’s default host platform explicitly (for example, lts-linux-x64 on an x86_64 Linux machine) refers to the exact same installation as lts without a platform suffix.

Keep in mind that installing another operating system’s host SDK does not make that platform’s binaries executable on your machine. If you want to compile code for another platform from your current machine, attach a cross-compilation SDK to your host toolchain using cjv target. A cross-compilation target SDK is an add-on to a host toolchain and cannot be set as the global default or active toolchain on its own.

Custom SDKs

For developers working on custom Cangjie SDK builds or operating in offline environments, cjv can manage local SDK directories and archives. To link an unpacked local SDK directory, run:

cjv toolchain link my-sdk /path/to/local/sdk
cjv default my-sdk

Linking a directory creates a lightweight reference to the SDK directory that you maintain yourself; running cjv uninstall my-sdk removes the reference in cjv while leaving your source directory untouched.

To create a managed custom SDK copy or attach local stdx, use cjv toolchain import <name> <archive|url>; see Custom SDKs. Custom toolchains are skipped by update and have no official downloads through component add.

To inspect all toolchains installed on your machine, run cjv toolchain list. To see which toolchain is active in your current directory and why, run cjv show active. Next, see Project toolchains for how cjv selects a toolchain for each project.

Project toolchains

When a proxy command such as cjc or cjpm runs, cjv selects a toolchain for the current directory. Commit cangjie-sdk.toml in the project root to declare the SDK version, components, and cross-compilation targets for developers and CI:

[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]

The version lts-1.0.5 above is an example; see Toolchains and versions for all supported channel and version formats.

Instead of writing the version string by hand, you can run cjv pin lts in your project root to write the resolved concrete release name to cangjie-sdk.toml (or cjv pin with no arguments to pin whichever toolchain is currently active). Existing components and targets entries in the file are preserved. In CI pipelines, you can run cjv pin --check to verify that the project file pins a concrete release without modifying it; see Automation and JSON interfaces.

Selection order

There are several ways to control and override which toolchain is active. cjv chooses the toolchain in the following order, using the first one that is specified:

  1. An explicit command-line selection, such as a global +name shorthand (cjv +nightly show) or a command’s --toolchain option.
  2. The CJV_TOOLCHAIN environment variable.
  3. A directory walk from the current working directory up toward the filesystem root. At each directory level, cjv checks for a local directory override before checking for cangjie-sdk.toml, stopping at the first match it finds.
  4. The global default toolchain set with cjv default.

Notice how step 3 works when walking up the directory tree: both directory overrides and cangjie-sdk.toml files are preferred by their proximity to your current directory. Within the same directory, a local directory override takes precedence over cangjie-sdk.toml; however, a cangjie-sdk.toml file in a child directory takes precedence over a directory override set on a parent directory. cangjie-sdk.toml files at different directory levels are never merged.

To verify which toolchain is active in your current directory and see which rule selected it, run:

cjv show active

Note that cjv run <toolchain> <command> always uses its explicit <toolchain> argument. Whenever an explicit command-line selection or CJV_TOOLCHAIN overrides cangjie-sdk.toml, the components and targets listed in cangjie-sdk.toml are not attached to that override.

The cangjie-sdk.toml file

The cangjie-sdk.toml file uses the TOML format. All settings live under the [toolchain] table:

FieldTypeMeaning
channelstringA release channel, version selector, or registered custom toolchain name
pathstringAn absolute path to a local SDK directory; mutually exclusive with channel
componentsstring[]Additional components to install (stdx, docs, stdx-docs); empty by default
targetsstring[]Cross-compilation target suffixes to install (such as ohos); empty by default

Toolchain file settings

channel and path

Every cangjie-sdk.toml file must specify either channel or path, but never both:

  • channel names an official release channel (lts, sts, nightly), a pinned version selector (lts-1.0.5, 1.2, nightly-2026-10-04), or a custom toolchain name registered via toolchain import or toolchain link.
  • path points directly to an unpacked SDK directory on the local filesystem using an absolute path:
[toolchain]
path = 'C:\SDKs\cangjie'

Because a path directive points directly to an external SDK directory whose contents are managed by its owner, components and targets do not trigger automatic installation when path is used.

components and targets

When channel selects a managed toolchain, you can list additional components and cross-compilation target SDKs that your project requires:

[toolchain]
channel = "sts"
components = ["stdx", "docs"]
targets = ["ohos", "android"]

In targets, always write target suffixes such as ohos or android rather than full host-target platform names like linux-x64-ohos. cjv normalizes letter case and underscores, expands comma-separated items, and removes duplicates automatically; empty target strings are rejected with an error.

When cangjie-sdk.toml selects the active toolchain, this declaration ensures the host SDK, the listed host components, and the listed target SDKs are prepared. See Cross-compilation for how to load a target SDK’s build environment when compiling.

Automatic installation

By default, the auto_install setting is true. Whenever you run a proxy command such as cjc or cjpm inside a project, cjv automatically downloads and installs any missing SDK, component, or target declared in the active cangjie-sdk.toml.

If you prefer missing requirements to fail immediately instead of downloading automatically, you can disable auto_install in your user settings:

cjv set auto-install false

You can also disable automatic installation for a single command invocation without changing your saved configuration by passing --no-auto-install (cjv --no-auto-install exec cjc --version) or by setting CJV_AUTO_INSTALL=0 in the environment for proxy commands. Explicit cjv install commands always run regardless of this setting.

Invalid project files

If cangjie-sdk.toml contains unrecognized keys under [toolchain], cjv prints a warning to stderr while still honoring all recognized fields. However, invalid TOML syntax, unknown component names, an empty file, or a missing/invalid channel or path will cause the command to fail with an error rather than silently falling back to another toolchain. If you want a directory to fall back to a parent directory’s configuration or the global default, delete the cangjie-sdk.toml file.

Local directory overrides

Directories can be assigned their own local toolchain override with cjv override. When a directory has an override, running cjc or cjpm inside that directory—or any of its subdirectories—uses the override toolchain without touching the project’s repository files:

cjv override set nightly
cjv override set lts --path /path/to/project
cjv override list
cjv override unset
cjv override unset --nonexistent

Per-directory overrides are saved in your user settings.toml file. Passing --nonexistent to cjv override unset cleans up stale overrides for directories that have been deleted from disk.

Components and offline documentation

Components are optional extension libraries and offline documentation attached to a toolchain. Each toolchain has its own components, which are removed when that toolchain is uninstalled:

ComponentContentsLocation relative to CJV_HOME
stdxDynamic and static extension librariesstdx/<tc>/{dynamic,static}
docsLanguage guide, standard library, and tool documentationdocs/<tc>/main/
stdx-docsExtension library (stdx) documentationdocs/<tc>/stdx/

When stdx is installed on the selected toolchain, proxy commands (cjc, cjpm), cjv exec, and cjv envsetup automatically export CANGJIE_STDX_PATH_DYNAMIC and CANGJIE_STDX_PATH_STATIC in the runtime environment. Documentation components (docs and stdx-docs) are used by cjv doc and do not alter runtime environment variables.

Installing and removing components

Components can be added when you first install a toolchain with the -c (--component) flag, or managed on an already-installed toolchain with cjv component:

cjv install nightly -c stdx,docs
cjv component add stdx docs --toolchain lts
cjv component list --toolchain lts
cjv component list --installed -q
cjv component remove stdx-docs
  • When --toolchain is omitted, cjv component operates on the currently active toolchain.
  • Passing --target <suffix> selects an installed cross-compilation target SDK belonging to that host toolchain (for example, cjv component add stdx --toolchain sts --target ohos).
  • Component names can be passed as multiple arguments or as a comma-separated list.
  • cjv component add skips components that are already installed; pass --reinstall if you want to reinstall them from the distribution source.

Not all components are published for every channel, version, or platform. Custom toolchains have no official upstream record in the distribution manifest, so cjv component add cannot download components for them. In team repositories, you can also list required components in cangjie-sdk.toml so cjv installs them automatically.

component list --names-only prints one name per line. Global --quiet / -q only hides progress, regardless of position. Old add --force and link --force remain hidden aliases for --reinstall and --replace.

How components behave during updates

When you run cjv update on a tracked channel (lts, sts, nightly), cjv updates the host SDK and all of its selected components together in a single transaction. Components attached to a pinned version (such as lts-1.0.5) remain unchanged. If you have linked a local stdx directory to a tracked channel, updating the channel preserves your local stdx link.

Linking a local stdx directory

If you build stdx from source or have a pre-extracted stdx directory on disk, you can attach it to a toolchain with cjv component link:

cjv component link stdx /path/to/local/stdx --toolchain lts --replace

The directory you point to must contain both dynamic/ and static/ subdirectories. Passing --replace replaces an existing stdx component on that toolchain. When you later run cjv component remove stdx, cjv removes its internal link entry while preserving your local source directory untouched. Note that docs and stdx-docs do not support local directory links.

Managing components on custom SDKs

Because cjv component commands record component manifests inside a cjv-managed toolchain installation, an external SDK directory referenced via cjv toolchain link <name> /path/to/sdk cannot be modified by cjv component—the owner of that external directory maintains its contents directly.

If you want cjv to manage components (such as linking a local stdx) for a custom SDK, install the custom SDK from a local archive or URL so that cjv extracts it into a managed directory first:

cjv toolchain import my-sdk ./cangjie-sdk.zip
cjv component link stdx /path/to/local/stdx --toolchain my-sdk

Viewing offline documentation with cjv doc

Once you have installed the docs or stdx-docs component, use cjv doc (or its alias cjv docs) to open the local HTML documentation in your default web browser:

cjv doc
cjv doc std
cjv doc dev-guide
cjv doc tools
cjv doc stdx --toolchain nightly
cjv doc --path

You can optionally specify a documentation topic:

  • No topic (cjv doc) — Opens the main documentation home page if docs is installed, or falls back to the stdx documentation home page if only stdx-docs is installed.
  • std — Opens the Cangjie standard library API reference (requires docs).
  • dev-guide (or book) — Opens the Cangjie developer guide (requires docs).
  • tools — Opens the Cangjie SDK tools manual (requires docs).
  • stdx — Opens the extension library documentation (requires stdx-docs).

Passing --path (or --json) prints the resolved local filesystem path to stdout without launching a browser. If the required documentation component is not installed yet, cjv doc tells you which cjv component add command to run.

Custom SDKs: directories, archives, and URLs

cjv toolchain link references an unpacked SDK directory; cjv toolchain import creates a managed installation from a local archive or HTTP(S) URL:

cjv toolchain link local-sdk /path/to/sdk
cjv toolchain import archive-sdk ./cangjie-sdk.zip
cjv toolchain import remote-sdk https://example.com/cangjie-sdk.tar.gz

Each of these commands registers an independent custom toolchain under the name you choose. Linking a custom toolchain does not change your global default selection; run cjv default <name> if you want to make it the default, or set channel = "<name>" in a project’s cangjie-sdk.toml.

The name you choose must follow the custom toolchain naming rules and cannot be an official channel or version name such as lts, sts, or nightly.

Depending on whether you pass an unpacked directory or an archive/URL, cjv manages the files differently:

SourceHow cjv installs itHow cjv uninstalls it
Unpacked directoryCreates a lightweight reference to the directory; requires bin/cjc (cjc.exe on Windows)Removes the link in cjv and leaves your source SDK directory untouched
Local archive or URLExtracts the archive into a real directory under <CJV_HOME>/toolchains/ managed by cjvDeletes the installed SDK copy and its attached components, while preserving your local source archive file

This distinction also affects component management:

  • Linked directories are maintained directly by the owner of that directory, so cjv component commands cannot add, link, or remove components on them.
  • Archive and URL installations live in a directory owned by cjv, so they can automatically install a bundled stdx archive or have a local stdx attached via cjv component link stdx.

Archive installation options

cjv toolchain import accepts these archive installation options:

OptionEffect
--sha256 <hex>Verify the archive against an expected 64-character hexadecimal SHA-256 digest before extracting
--replaceReplace an existing custom toolchain with the same name
--no-stdxSkip installing a bundled stdx archive when extracting an outer CI bundle

These three options apply only to archives and URLs; passing them when linking an unpacked directory produces an error. If you omit --sha256 for an archive or URL, cjv skips checking an expected digest but still validates the archive format and SDK directory structure.

The old archive/URL forms of toolchain link still work with a migration note; their --force replacement flag corresponds to import --replace.

Supported archive layouts

cjv toolchain import supports two archive layouts out of the box:

  1. A bare SDK archive (.tar.gz or .zip) containing a single complete cangjie/ SDK directory with its bin/, lib/, tools/, runtime/, and other standard subdirectories.
  2. An outer CI bundle ZIP (such as the artifact produced by cangjie-build CI workflows) that wraps an inner SDK archive and an optional inner stdx archive:
cangjie-sdk-<sdk_name>-<version>.<tar.gz|zip>
cangjie-stdx-<sdk_name>-<version>.<stdxver>.<tar.gz|zip>  # optional

Inside the inner stdx archive, cjv looks for dynamic/ and static/ inside a platform directory. When a bundled stdx archive is present, cjv installs it automatically unless you pass --no-stdx. If extracting the bundled stdx fails, cjv keeps the successfully installed SDK and reports a warning.

Note that archive installations require an SDK built for your current host operating system. If you want to cross-compile for another operating system, attach a cross-compilation target SDK that runs on your host rather than installing another operating system’s host SDK archive.

Once installed, you can inspect or remove an archive-based custom toolchain with the standard commands:

cjv component list --toolchain archive-sdk
cjv uninstall archive-sdk

Cross-compilation

A host toolchain runs on the host platform (for example, linux-x64) and compiles programs for that platform by default. A cross SDK runs on the same host and provides compiler tools and libraries for another target platform, such as ohos or android.

cjv manages cross SDKs as attachments to an installed host toolchain. A target SDK’s release version always matches its host toolchain’s release, and the set of available targets depends on what the upstream distribution manifest publishes for that release and host.

Installing and inspecting targets

You can install a cross-compilation target when installing a host toolchain with --target (-t), or add it to an already-installed host toolchain with cjv target add:

cjv install sts --target ohos
cjv target list --toolchain sts
cjv target add android --toolchain sts
cjv target list --toolchain sts --installed
  • cjv target add installs the requested target SDKs for the host toolchain’s currently installed release without upgrading the host SDK itself.
  • cjv target list queries the distribution manifest to show all targets published for that host release, marking which ones are already installed.
  • cjv target list --installed reads local installation state only and works completely offline.

When naming a target on the command line or in cangjie-sdk.toml, always write the target suffix—such as ohos, android, or ohos-arm32—rather than a full host-target platform key like linux-x64-ohos. Both cjv install and cjv target add accept repeated --target flags or comma-separated values (such as --target ohos,android).

Using a target SDK

By default, the cjc and cjpm proxy binaries in <CJV_HOME>/bin select your host SDK environment. When you want to invoke tools or link against libraries from an installed cross SDK, load its environment into your current shell with cjv envsetup:

eval "$(cjv envsetup +sts --target=ohos)"
cjc --version

In Windows PowerShell:

cjv envsetup +sts --target=ohos | Invoke-Expression

Keep in mind that installing a target SDK with cjv (or listing targets in cangjie-sdk.toml) prepares the cross SDK files on disk, but does not automatically turn an ordinary cjpm build into a cross-compiled build. Compiler flags, target sysroots, system libraries, and linker settings depend on your target platform and project build scripts; see the official Cangjie SDK documentation for target-specific compiler options, and see Running commands and setting the environment for how envsetup manages your shell session.

Target components, updates, and removal

Each installed cross SDK has its own independent component set—host stdx libraries do not substitute for target stdx libraries. Once a target SDK is installed, pass --target <suffix> to cjv component commands to manage components for that target:

cjv component add stdx --toolchain sts --target ohos
cjv component list --toolchain sts --target ohos
cjv target remove ohos --toolchain sts

When you run cjv update on a tracked channel (lts, sts, nightly), cjv stages the updated host SDK, all of its installed cross targets, and all selected components before publishing them together in one atomic step. By default, if a required target or component is missing from the new release, cjv blocks the update and preserves your working installation (on nightly, it searches published history for a release that includes all required targets and components). If you want cjv to skip and remove unavailable optional targets or components during an update, pass --allow-missing; see the Command reference.

To remove a cross SDK and its target components while keeping the host toolchain intact, run cjv target remove. Because a cross SDK is always attached to a host toolchain, it cannot be set as the global default or active toolchain on its own.

Configuration

cjv stores your personal user settings in a TOML file at ~/.cjv/settings.toml (or %USERPROFILE%\.cjv\settings.toml on Windows) by default. You can select an alternate user settings file for a command or session with --config <path> or CJV_CONFIG_FILE, where the command-line --config flag takes precedence. Note that CJV_HOME and the home setting only relocate the data directory (toolchains/, cache/, etc.) and do not move settings.toml.

A typical settings.toml file looks like this:

version = 1
default_toolchain = "lts"
auto_self_update = "check"
auto_install = true

[overrides]
"/home/me/project-a" = "sts"

Settings

Most day-to-day settings can be updated through cjv subcommands (cjv default, cjv set, cjv override), while advanced distribution settings can be edited in settings.toml directly:

FieldDefault or purposeHow to change it
versionSettings format version maintained by cjvWritten and migrated automatically
default_toolchainGlobal default toolchaincjv default <name>; pass none to clear it
auto_self_updatecheck (report updates); also accepts enable or disablecjv set auto-self-update <value>
auto_installtrue (install missing requirements of the selected toolchain)cjv set auto-install <true|false>
homeData directory; defaults to ~/.cjvcjv set home <path>
default_hostDefault host platform; detected automaticallycjv set default-host <goos-goarch>
manifest_urlDefault LTS/STS manifest URL; nightly uses its sibling nightly.jsonEdit settings.toml
dist_serverBase URL serving both versions.json and nightly.jsonEdit settings.toml
link_modehardlink or copy; defaults to hardlinkEdit settings.toml
overridesPer-directory toolchain mapping tablecjv override set / cjv override unset

Automatic updates

The auto_self_update setting controls how cjv handles updates to the cjv binary itself when you run a full cjv update (that is, without specifying individual toolchain names or a global +name selector):

  • check (default) — Checks whether a newer release of cjv is available and prints a notice, without installing it automatically.
  • enable — Automatically downloads and installs any available update to cjv during cjv update.
  • disable — Skips checking for or installing cjv self-updates during cjv update.

Local development builds of cjv (which report their version as dev) automatically skip release checks. Regardless of auto_self_update, you can always update cjv manually by running cjv self update, or suppress the check for a single run with cjv update --no-self-update.

Data directory and host platform

When you run cjv set home <path>, cjv resolves relative paths to an absolute path before writing settings.toml. Running cjv set home "" explicitly resets the data directory back to the default ~/.cjv.

The default_host setting uses Go platform tuples such as linux-amd64 or darwin-arm64. Note that this differs slightly from the linux-x64 spelling used in toolchain names.

Inheritance and temporary overrides

On managed machines, user settings in ~/.cjv/settings.toml override system fallback settings (/etc/cjv/settings.toml on Unix, C:\ProgramData\cjv\settings.toml on Windows) field by field. Any field that is not present in your user settings file continues to inherit its value from the system fallback file, whereas explicit false values and empty strings "" in your user file count as explicit user overrides.

When you run cjv set, cjv writes only the specific field you modified so that other unset fields continue to inherit from the system fallback file. To restore system inheritance for a field, delete that key from your user settings.toml.

Here is how cjv resolves precedence across environment variables and configuration files:

  • Data directory precedence: CJV_HOME environment variable, then home in merged settings, then ~/.cjv.
  • Distribution source precedence: CJV_DIST_SERVER environment variable, then dist_server in merged settings, then manifest_url. Environment variable overrides are temporary and are never persisted to disk when you run cjv set.
  • Custom config file (--config): Passing --config <path> (or setting CJV_CONFIG_FILE) replaces only the user settings file; system fallback settings, project toolchain files, and environment variables still apply.
  • Per-invocation auto-install overrides: Passing --no-auto-install disables automatic installation for that invocation, and CJV_AUTO_INSTALL=0 or 1 temporarily overrides auto_install for the current process tree without modifying settings.toml.

Unrecognized keys in settings.toml produce a warning on stderr, while invalid TOML syntax or an unsupported future version number causes cjv to exit with an error.

Data layout

cjv organizes all installed toolchains, components, caches, and rollback snapshots under <CJV_HOME>:

<CJV_HOME>/
  bin/              # cjv binary and SDK proxy entry points (cjc, cjpm, ...)
  toolchains/<tc>/  # Installed host SDKs and cross-compilation target SDKs
  stdx/<tc>/        # Installed stdx dynamic/ and static/ libraries
  docs/<tc>/main/   # Offline main documentation
  docs/<tc>/stdx/   # Offline extension library (stdx) documentation
  downloads/        # Installation staging and resumable partial downloads
  cache/            # Cached manifests and SHA-256-verified archives
  history/<tc>/     # Complete toolchain group snapshots from channel updates

Your settings.toml file lives inside <CJV_HOME> only when <CJV_HOME> uses the default ~/.cjv path. You can run cjv show home at any time to see the effective data directory and which configuration source selected it.

Download cache

When cjv downloads an archive that has an expected SHA-256 checksum, partial downloads are kept in downloads/ if a network failure or interruption occurs so the next command can resume where it left off and verify the complete file. Successful operations clean up their own staging files, and a full cjv update across all toolchains that succeeds completely also cleans up any leftover files in downloads/.

Separately, <CJV_HOME>/cache/ retains downloaded version manifests and SHA-256-verified archives after installation succeeds so they can be reused later. Cached archives are keyed by source URL and SHA-256 digest and are re-verified every time they are reused (archives without a checksum are never stored in the reusable cache).

When you pass --offline or set CJV_OFFLINE=1, cjv makes no network requests and relies exclusively on local installations and cache/. Keep in mind that cached manifests reflect the last successful online fetch and may not include newer upstream releases; if a needed manifest or archive is absent from cache/, the offline command fails with an error.

You can manage the reusable cache with the cjv cache subcommands:

  • cjv cache dir — Print the path to the cache directory.
  • cjv cache list — Inspect cached manifests and archives.
  • cjv cache prune --max-age 720h — Remove cached entries older than the given duration.
  • cjv cache clean — Remove all cached manifests and archives.

Cleaning the cache never deletes your installed SDKs. See Automation and JSON interfaces for CI caching workflows.

SDK file reuse

By default, link_mode = "hardlink" deduplicates identical regular files across SDK installations that share the same release, platform, and SHA-256 digest. Installation metadata and components remain separate, and if hard links are not supported by the underlying filesystem, cjv automatically falls back to keeping independent file copies.

Because hard-linked files share the same underlying disk content, manually editing a file in place inside <CJV_HOME>/toolchains/ can affect other hard-linked SDK installations. If you need completely independent file copies so you can modify SDK files in place, set link_mode = "copy" in settings.toml (this setting applies to future installations and does not split existing hard links). When cjv update updates a toolchain, it always publishes a replacement directory tree rather than modifying shared files in place.

Automation and JSON interfaces

This page documents cjv usage in CI, build scripts, and editor integrations: version pinning and validation, configuration isolation, offline caches, read-only diagnostics, update rollback, and --json output.

Pin a project version

In a project repository, running cjv pin lts writes the resolved concrete release name (such as lts-1.0.5) to cangjie-sdk.toml in the current directory while preserving any existing components, targets, and custom keys (comments and formatting are rewritten). If you omit the toolchain name (cjv pin), cjv pins whichever toolchain is currently active. When pinning a tracked channel that is already installed on your machine, cjv pin prefers your locally installed release first and never downloads an SDK.

pin only writes project configuration; it does not create a fixed-version installation. lts and lts-1.0.5 are independent installation identities. If only lts is installed, the first tool invocation after pinning still installs lts-1.0.5 according to auto_install; you can also run cjv install lts-1.0.5 beforehand. Updating or uninstalling lts then leaves the project’s fixed 1.0.5 installation available. The default link_mode = "hardlink" reuses regular SDK files when the release, platform, checksum, and file contents match, while installation metadata and components stay independent.

Commit cangjie-sdk.toml to version control so every contributor and CI job selects the exact same SDK version:

cjv pin lts
cjv pin --check

cjv pin --check verifies that the current directory’s cangjie-sdk.toml pins a concrete release without modifying the file or making network requests. Artifact checksums come from the distribution manifest or an upstream checksum sidecar, rather than the project file; see Internal distribution source for checksum availability.

Configuration and network access

Isolating CI directories and settings

In CI jobs, you often want to isolate both the data directory and the user settings file inside the workspace so builds do not read or mutate the runner’s home directory:

export CJV_HOME="$PWD/.cjv-data"
export CJV_CONFIG_FILE="$PWD/ci-settings.toml"
cjv install lts
cjv --offline --no-auto-install exec cjc --version

CJV_HOME must be an absolute path. Note that --config and CJV_CONFIG_FILE replace only the user settings file; system fallback settings, cangjie-sdk.toml project selection, and other environment variables still apply. If your runner also needs to isolate or override the system fallback file, set CJV_FALLBACK_SETTINGS separately.

Offline caches and network flags

To run cjv with --offline (or CJV_OFFLINE=1), the required manifests, SDK archives, and component archives from the configured distribution source must be present in <CJV_HOME>/cache/ beforehand. Whenever an online installation succeeds, cjv retains the manifest and all SHA-256-verified archives in cache/ (archives without checksums are not retained in the reusable cache). You can inspect the cached items with cjv cache list --json, and supply the populated cache/ directory alongside cangjie-sdk.toml to your offline build environment under the same distribution source configuration.

If cache/ contains damaged metadata records, orphaned archive files, or incomplete temporary files, cjv cache list --json reports them via the optional problem field while still listing healthy entries. Running cjv cache clean removes all cjv-owned cache files (including damaged ones), whereas cjv cache prune --max-age <duration> filters entries by age. Note that if an online query succeeds but saving its optional cache entry fails, cjv prints a warning to stderr and still returns the successful query result.

  • --no-auto-install prevents implicit installation by proxies, run, exec, and default selection. Explicit install still works. Inspection commands and envsetup never install automatically.
  • --offline prevents cjv itself from making network requests, but does not restrict network access by child programs spawned via run, exec, or proxy binaries.

Inspect and repair

You can use these commands in automation or troubleshooting scripts to inspect environment health, preview updates, or repair an installation:

cjv doctor --json
cjv update --dry-run --json
cjv install lts --reinstall
  • cjv doctor performs a read-only check of your settings, active toolchain selection, proxy entry points in <CJV_HOME>/bin, installation records, and the presence of key SDK files, suggesting concrete repair commands when it detects an issue. It does not compute SHA-256 digests for every individual file inside an installed SDK, and it exits with a nonzero code (1) whenever a check fails.
  • cjv update --dry-run resolves compatible releases, blockers, and the self-check/update policy for full updates, without downloading archives or changing installations or caches.
  • cjv install <name> --reinstall reinstalls the current named release while retaining components and targets. Ordinary install preserves installed releases; update advances channels. --allow-missing permits skipping/removing unavailable optional items; old --force remains compatible.

Update history and rollback

Whenever updating a tracked channel (lts, sts, nightly) changes the release or SHA-256 digest of its host SDK or an installed cross target, cjv retains a complete snapshot of the previous toolchain group—including the host SDK, tracked cross targets, offline documentation, and stdx—under <CJV_HOME>/history/.

By default, each tracked channel retains its 2 most recent snapshots. Initial installations, --reinstall repairs of the same release, and standalone target add or component add operations do not create update snapshots. Fixed-version installations (such as lts-1.0.5) remain independent of tracking-channel history.

cjv toolchain history list lts
cjv toolchain rollback lts
cjv toolchain history prune lts --keep 1
  • cjv toolchain rollback <channel> [snapshot] restores the newest snapshot when [snapshot] is omitted, or restores a specific snapshot ID when given. Before replacing the installation, rollback verifies the local snapshot’s contents and saves the current toolchain group as a snapshot so that the rollback itself can be undone.
  • cjv toolchain history prune [channel] [--keep N] removes older snapshots. Because each snapshot stores independent file copies (including the target contents of linked components), snapshots consume additional disk space and are not removed by cjv cache clean. Passing --keep 0 clears all snapshots while preserving your active installations. Note that --keep applies only to that prune invocation; future updates still retain 2 snapshots automatically. Never edit files inside <CJV_HOME>/history/ by hand.

Handling damaged snapshots

cjv toolchain history lists valid, readable snapshots in snapshots and reports any damaged records—along with their failure causes—in the optional invalid_snapshots array.

When you run history prune with a nonzero --keep value, cjv retains that many readable snapshots and leaves damaged entries in place so you can inspect them; running history prune --keep 0 removes both readable and damaged entries. If the newest snapshot is damaged, running cjv toolchain rollback <channel> without an explicit snapshot ID refuses to silently guess an older release and requires you to specify a valid <snapshot> ID explicitly. Every selected snapshot must pass full content verification before restoration.

JSON compatibility

Commands supporting --json write one structured document to stdout and logs/warnings to stderr. run, exec, init, and completion reject JSON: execution preserves child output, initialization uses an interactive flow, and completion emits a shell script directly.

Bare cjv --json and cjv show --json return the same status structure. Installation entries include name, actual release, and kind (tracking, pinned, custom). set --json returns key, value, and changed, including changed: false for no-ops. override list --json always has an overrides array; set returns directory/toolchain fields and unset returns a removed directory array. SDK and self-uninstall require explicit --yes in non-interactive or JSON mode.

Clients of the old bare-command JSON summary must migrate the active string and installed name array to the show status structure: active is an object with name, source, and installation status, and entries live in installed.toolchains. The existing show --json shape is unchanged.

When building automation around --json, follow these compatibility rules:

  • Per-command success payloads: Success fields are specific to each command. Clients should ignore unrecognized object keys and enum values they do not use.
  • Versioned schemas (schema_version): Payloads that include a schema_version field preserve existing field meanings and types within that version. Adding new optional fields does not increment schema_version; incompatible changes increment it.
  • Unversioned payloads: Existing commands without a schema_version field keep their current output structure; do not assume they share fields with other commands.
  • Collections and optional fields: Required collections are always JSON arrays ([] when empty), while optional fields may be omitted or null according to each command’s existing behavior.
  • Machine-readable error handling: Always branch on the process exit code and error.code, never on the localized human-readable error.message.

For example, an empty cache returns:

{"schema_version":1,"path":"/home/user/.cjv/cache","entries":[]}

The following JSON Schema describes the stable fields of cjv cache list --json while allowing future optional fields:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["schema_version", "path", "entries"],
  "properties": {
    "schema_version": {"const": 1},
    "path": {"type": "string"},
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["key", "kind", "url", "size", "updated"],
        "properties": {
          "key": {"type": "string"},
          "kind": {"type": "string", "examples": ["metadata", "artifact"]},
          "url": {"type": "string"},
          "sha256": {"type": "string"},
          "size": {"type": "integer", "minimum": 0},
          "updated": {"type": "string", "format": "date-time"}
        }
      }
    }
  }
}

Error objects and automatic installation causes

When a command fails, cjv writes {"error":{"code":"...","message":"...","details":{}}} to stdout and exits with a nonzero status code. New error codes may be added over time, so clients should handle unknown code values gracefully; the fields inside details depend on the specific code.

cjv doctor --json is an intentional exception: when it detects diagnostic problems, it still outputs its normal report object containing checks with "ok": false and exits with code 1, rather than wrapping the response in an error object.

When automatic installation fails while resolving a toolchain or component, the top-level error code remains TOOLCHAIN_NOT_INSTALLED or COMPONENT_NOT_INSTALLED, and details.cause preserves the underlying failure’s code, message, and details:

  • OFFLINE_CACHE_MISS — A required manifest or archive was not found in <CJV_HOME>/cache/ while running with --offline.
  • CHECKSUM_MISMATCH — A downloaded or cached archive failed SHA-256 verification.
  • HTTP_ERROR and NETWORK_ERROR — Distinguish unsuccessful HTTP status responses from lower-level connection or transport failures.
  • CANCELED and DEADLINE_EXCEEDED — Indicate that the operation was canceled by a signal or exceeded the download timeout.

When automatic installation is disabled (--no-auto-install, CJV_AUTO_INSTALL=0, or auto_install = false), a missing installation has no details.cause because no installation was attempted.

Environment variables

You can set environment variables before starting cjv to override configuration settings for that process and its children without modifying settings.toml:

CJV_LOG=debug cjv show active

In Windows PowerShell:

$env:CJV_LOG = "debug"
cjv show active

Quick reference

VariableDefaultPurpose
CJV_HOME~/.cjv, or the home settingAbsolute data directory; does not move user settings.toml
CJV_CONFIG_FILE~/.cjv/settings.tomlUser settings file (--config takes precedence); system fallback and project selection still apply
CJV_FALLBACK_SETTINGSSystem settings pathSelect an alternate system fallback settings file
CJV_TOOLCHAINUnsetToolchain name or absolute SDK path; overrides directory overrides, cangjie-sdk.toml, and the default toolchain
CJV_AUTO_INSTALLThe auto_install setting0 disables or 1 enables automatic installation without saving settings
CJV_OFFLINEUnsetDisable cjv network requests when set to 1; cached files remain available
CJV_DIST_SERVERUnsetOverride the toolchain distribution root
CJV_ALLOW_INSECURE_MANIFESTUnsetAllow plain http:// manifests from non-loopback hosts when set to 1
CJV_MAX_RETRIES3Maximum retries after a failed download (non-negative integer)
CJV_DOWNLOAD_TIMEOUT180HTTP download timeout in seconds (positive integer)
CJV_NO_PATH_SETUPUnsetSkip automatic PATH setup when set to 1
CJV_LOGwarnLog level on stderr: debug, info, warn, or error (unknown values fall back to warn)
CJV_LANGSystem localeOverride the CLI interface language, such as zh, en, or ja

Detailed behavior

  • Paths and configuration (CJV_HOME, CJV_CONFIG_FILE, CJV_FALLBACK_SETTINGS) — CJV_HOME selects an absolute data directory for toolchains, components, caches, and rollback history. It does not move the user settings.toml file. To isolate CI settings, also set CJV_CONFIG_FILE or pass --config <path>. See Configuration for precedence rules.
  • Toolchain selection and auto-install (CJV_TOOLCHAIN, CJV_AUTO_INSTALL) — If CJV_TOOLCHAIN is set, it overrides directory overrides, cangjie-sdk.toml, and the default toolchain (only an explicit CLI flag like +name or --toolchain ranks higher). CJV_AUTO_INSTALL=0 or 1 temporarily overrides auto_install for the current process tree.
  • Networking, retries, and HTTPS enforcement (CJV_OFFLINE, CJV_DIST_SERVER, CJV_MAX_RETRIES, CJV_DOWNLOAD_TIMEOUT, CJV_ALLOW_INSECURE_MANIFEST) — If CJV_MAX_RETRIES or CJV_DOWNLOAD_TIMEOUT is set to an unparseable or out-of-range value, cjv falls back to its default (3 retries and 180 seconds). Because version manifests supply both download URLs and SHA-256 checksums, cjv requires https:// for remote manifests by default; loopback test servers (localhost, 127.0.0.1, ::1) are exempt, and setting CJV_ALLOW_INSECURE_MANIFEST=1 permits plain http:// on non-loopback hosts when testing internal infrastructure.
  • Variables injected into SDK environments (CANGJIE_HOME, CANGJIE_STDX_PATH_*) — When stdx is installed for the selected toolchain, cjv automatically injects CANGJIE_STDX_PATH_DYNAMIC and CANGJIE_STDX_PATH_STATIC into the SDK’s runtime environment, pointing to the component’s dynamic/ and static/ directories. These variables are managed by cjv and normally need no manual configuration; see Running commands and setting the environment.
  • Proxy and installer script variables (HTTPS_PROXY, CJV_VERSION, CJV_UPDATE_ROOT) — See Network proxies for HTTP(S) and SOCKS5 proxy variables. During initial script installation, install.sh and install.ps1 read CJV_VERSION to select a cjv release tag (command-line --version / -Version takes precedence). CJV_UPDATE_ROOT (along with CJV_GITHUB_ROOT and CJV_GITCODE_ROOT) selects the initial download base URL for the installer scripts and takes precedence over version selection, though it does not override cjv self update on an already-installed binary. See Install cjv for examples.

Network proxies

cjv uses standard proxy environment variables for network access. Proxy settings apply to version manifests, SDK archives, components, and self-update requests.

Configuring a proxy in your shell

Set the proxy environment variables in your shell before running cjv:

  • On Linux, macOS, or HarmonyOS HiShell (Bash or Zsh):
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,artifacts.corp.example
cjv install lts
  • On Windows PowerShell:
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,artifacts.corp.example"
cjv install lts
  • On Windows Command Prompt (cmd.exe):
set HTTPS_PROXY=http://proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,artifacts.corp.example
cjv install lts

Supported variables and URL schemes

VariablePurpose
HTTPS_PROXY / https_proxyProxy server for https:// requests
HTTP_PROXY / http_proxyProxy server for http:// requests
NO_PROXY / no_proxyComma-separated list of hostnames, domains, or IP addresses to contact directly

Proxy URLs support the http://, https://, and socks5:// schemes.

Note: cjv uses Go’s standard HTTP proxy resolution and does not read ALL_PROXY or all_proxy. If your shell environment only defines ALL_PROXY, set HTTPS_PROXY (and HTTP_PROXY if needed) explicitly before running cjv.

Corporate TLS inspection and slow connections

  • Private CA certificates — If your organization uses a TLS-inspecting proxy with a private Certificate Authority (CA), add the organization’s root CA certificate to your operating system’s trust store so cjv can verify HTTPS connections.
  • Bypassing the proxy for internal mirrors — If you use an internal distribution server alongside an outbound internet proxy, add your internal mirror’s hostname or domain to NO_PROXY so cjv connects to it directly.
  • Tuning retries and timeouts — On slow or high-latency connections, you can increase CJV_MAX_RETRIES (default 3) and CJV_DOWNLOAD_TIMEOUT (default 180 seconds); see Environment variables for details.

Enterprise and offline deployment

Organizations can deploy cjv across developer workstations and CI runners under a variety of network policies:

  • Outbound access via proxy — When client machines can reach upstream servers through a corporate proxy, configure network proxy variables and your corporate CA certificate.
  • Internal-only network — When clients can only reach internal hosts, publish approved SDKs, components, and manifests to an internal distribution server and point dist_server at it.
  • Fully air-gapped environments — Import local archives with toolchain import, or reference pre-staged directories with toolchain link.

Keep in mind that dist_server controls Cangjie SDK and component distribution only. Upgrades to the cjv binary itself and cjpm package dependency repositories are configured and managed separately.

Deploy clients

You can distribute the cjv executable directly through your enterprise endpoint management system, or host the installer scripts (install.sh, install.ps1) and release archives on an internal HTTP(S) server:

$env:CJV_UPDATE_ROOT = "https://artifacts.corp.example/cjv/releases/latest/download"
& ([scriptblock]::Create((irm https://artifacts.corp.example/cjv/install.ps1))) `
  -Yes -DefaultToolchain none -NoModifyPath

CJV_UPDATE_ROOT directs the installer script to download cjv from your internal release directory (which must serve the platform archives alongside checksums.txt). Passing -NoModifyPath (or --no-modify-path on Unix) leaves shell profiles and registry PATH values untouched when your endpoint management software configures PATH centrally.

In automated rollouts, it is best practice to separate deployment into three distinct steps—install cjv, distribute the system fallback settings file, and then install the approved SDKs—so that each step reports its own exit status.

System fallback settings

Before reading a user’s personal ~/.cjv/settings.toml file, cjv consults a system-wide fallback settings file:

Operating systemDefault fallback settings file
WindowsC:\ProgramData\cjv\settings.toml
Linux and macOS/etc/cjv/settings.toml

You can also point cjv at a custom fallback file using the CJV_FALLBACK_SETTINGS environment variable. A typical enterprise fallback configuration looks like this:

version = 1
dist_server = "https://artifacts.corp.example/cjv/dist"
default_toolchain = "lts-1.0.5"
auto_self_update = "disable"
auto_install = false

Replace lts-1.0.5 with your organization’s approved release. With auto_install = false, missing SDKs or components fail immediately with a clear error rather than triggering an unapproved download, ensuring that all toolchains are supplied through your managed deployment workflow. On multi-user machines, make sure each user account has its own separate CJV_HOME.

Note that fallback settings provide default values: user settings in ~/.cjv/settings.toml can still override individual fields, and environment variables like CJV_DIST_SERVER take precedence at runtime (see Configuration). To enforce strict source and version policies, combine system fallback settings with network ACLs, filesystem permissions, and managed software distribution.

Install approved versions

On internal clients connected to your mirror, install and verify the approved release:

cjv install lts-1.0.5 -c stdx
cjv default lts-1.0.5
cjv which cjc
cjc --version

Use the exact same full version name (lts-1.0.5) in each project’s cangjie-sdk.toml. If teams use nightly builds, pin full nightly version strings as well and retain their SDK and component archives in your internal distribution.

Fully offline clients

On air-gapped workstations or build nodes without an internal HTTP server, register toolchains from local archives or pre-staged directories:

cjv toolchain import corp-sdk ./cangjie-sdk.zip --sha256 <approved-sha256>
cjv component link stdx /opt/corp/cangjie-stdx --toolchain corp-sdk
cjv default corp-sdk

Pass --sha256 <approved-sha256> when importing an archive so cjv verifies the archive’s integrity before extraction. Alternatively, you can link an unpacked read-only SDK directory (cjv toolchain link corp-sdk /opt/corp/sdk), in which case the owner of that directory maintains its components directly. In project repositories, reference the custom toolchain name (channel = "corp-sdk") in cangjie-sdk.toml, and make sure any required cjpm project dependencies are pre-staged for offline builds.

See Custom SDKs for supported archive formats. Because docs and stdx-docs do not support local directory links, install them from a distribution source before disconnecting the machine (or include them in a pre-staged CJV_HOME).

Publication and validation

When publishing new releases to your internal distribution server, always upload and verify all archive files before atomically replacing versions.json or nightly.json and advancing latest. Note that in nightly.json, latest is a top-level field and clients may search historical versions in that file when resolving compatible components or cross targets. Always retain all versions that are pinned by active projects.

Before rolling out updates broadly, validate the setup using both an ordinary developer account and your actual CI service account:

  • Confirm that LTS/STS operations read versions.json and nightly operations read nightly.json, and that all resolved artifact URLs stay within approved internal hosts.
  • Confirm that approved releases and components install cleanly, and that cjv which cjc and cjc --version identify the intended SDK.
  • Confirm that projects with prepared toolchains and dependencies build offline as expected.
  • Confirm that corporate CA certificates, proxy settings, and NO_PROXY rules work properly, and that missing requirements produce the expected errors when auto_install is disabled.

With auto_self_update = "disable", distribute cjv binary upgrades through your enterprise software management tool. Keep in mind that running cjv self update explicitly still contacts the binary’s compiled-in upstream update source, so network firewall policies should restrict external update hosts where appropriate.

Internal distribution source

The dist_server setting in settings.toml (or the CJV_DIST_SERVER environment variable) configures the root URL from which cjv fetches version manifests and toolchain archives. For example:

dist_server = "https://artifacts.corp.example/cjv/dist"

Under that root URL, cjv reads two channel-specific manifest files:

https://artifacts.corp.example/cjv/dist/versions.json  # LTS and STS channels
https://artifacts.corp.example/cjv/dist/nightly.json   # nightly channel
  • LTS and STS operations read versions.json only.
  • Nightly operations read nightly.json only.
  • cjv check and cjv update load only the manifest files required by your locally installed channels.
  • Relative SDK and component url fields inside a manifest are resolved against dist_server, whereas absolute https:// URLs are used exactly as written.

Distribution source precedence is CJV_DIST_SERVER, then dist_server from merged settings, and finally manifest_url. In CI pipelines, you can set CJV_DIST_SERVER to test a staging mirror before promoting manifests to production.

We recommend organizing your internal artifact repository so dist/ serves toolchains and manifests while releases/ serves cjv binary releases:

Enterprise artifact repository
└── cjv/
    ├── dist/                         # dist_server points here
    │   ├── versions.json             # LTS / STS and their components
    │   ├── nightly.json              # nightly and its components
    │   ├── sdk/
    │   ├── components/
    │   └── nightly/
    └── releases/                     # cjv archives and checksums.txt

The distribution endpoint simply needs to serve machine-readable, read-only files over HTTPS GET. You can enforce access control using network allowlists, device certificates, or an enterprise reverse proxy.

versions.json contract

In versions.json, the top-level channels object contains the lts and sts channel objects:

{
  "channels": {
    "lts": {
      "latest": "1.0.5",
      "versions": {
        "1.0.5": {
          "linux-x64": {
            "name": "cangjie-sdk-linux-x64-1.0.5.tar.gz",
            "url": "sdk/cangjie-sdk-linux-x64-1.0.5.tar.gz",
            "sha256": "<64-character hexadecimal SHA-256>"
          }
        }
      }
    },
    "sts": {
      "latest": "1.1.0",
      "versions": {
        "1.1.0": {
          "linux-x64": {
            "name": "cangjie-sdk-linux-x64-1.1.0.tar.gz",
            "url": "sdk/cangjie-sdk-linux-x64-1.1.0.tar.gz",
            "sha256": "<64-character hexadecimal SHA-256>"
          }
        }
      }
    }
  }
}

nightly.json contract

Unlike versions.json, nightly.json directly represents a single channel at the top level with latest, versions, and optional components (do not wrap nightly.json inside channels.nightly):

{
  "latest": "1.2.0-alpha.20260822010101",
  "versions": {
    "1.2.0-alpha.20260822010101": {
      "linux-x64": {
        "name": "cangjie-sdk-linux-x64-1.2.0-alpha.20260822010101.tar.gz",
        "url": "nightly/20260822/cangjie-sdk-linux-x64-1.2.0-alpha.20260822010101.tar.gz",
        "sha256": "<64-character hexadecimal SHA-256>"
      }
    }
  },
  "components": {
    "1.2.0-alpha.20260822010101": {
      "docs": {
        "name": "cangjie-docs-html-1.2.0-alpha.20260822010101.tar.gz",
        "url": "nightly/20260822/cangjie-docs-html-1.2.0-alpha.20260822010101.tar.gz",
        "sha256": "<64-character hexadecimal SHA-256>"
      }
    }
  }
}

Every SDK entry contains name, url, and sha256. On upstream nightly builds, sha256 may temporarily be empty while artifacts finish publishing, in which case cjv fetches <url>.sha256; on an internal enterprise mirror, you should populate sha256 directly in the manifest. Component entries also accept an optional sha256 field—populating it ensures clients verify component archives and retain them in the reusable offline cache.

The version key under versions determines the toolchain version name, while url identifies the archive file to download. When first installing or explicitly updating the tracked nightly channel, cjv starts from latest and searches published history in nightly.json if required components or cross targets are missing from the newest build (without downgrading an existing installation unless --allow-downgrade is passed). A full pinned nightly name selects that exact release directly.

Component format

Within each channel object (channels.lts, channels.sts, or the top level of nightly.json), components is indexed by version. docs and stdx-docs each point to a single archive per version, whereas stdx is further indexed by component platform:

{
  "components": {
    "1.0.5": {
      "stdx": {
        "linux-x64": {
          "name": "stdx-linux-x64.tar.gz",
          "url": "components/stdx-linux-x64.tar.gz",
          "sha256": "<64-digit hexadecimal SHA-256>"
        }
      },
      "docs": { "name": "docs.tar.gz", "url": "components/docs.tar.gz" },
      "stdx-docs": { "name": "stdx-docs.tar.gz", "url": "components/stdx-docs.tar.gz" }
    }
  }
}

Combine this components fragment with latest and versions inside the channel object. Cross-compilation target SDKs are stored under versions[version][platform] using host-target keys such as linux-x64-ohos, while their corresponding stdx archives use component platform names such as ohos-aarch64.

Publishing order

When updating your internal mirror, follow this sequence so clients never see a manifest pointing to missing files:

  1. Mirror and verify all approved SDK, cross-target, and component archives.
  2. Compute the 64-character SHA-256 digest for each SDK archive and component archive.
  3. Upload all archives to their target paths first and verify HTTPS GET access from a standard client account.
  4. Generate versions.json and nightly.json independently, retaining every exact version still referenced by project cangjie-sdk.toml files.
  5. Atomically replace the manifest files on the server, advancing latest only after all artifacts for that release are in place.

See Publication and validation for the end-to-end client verification checklist.

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.

Common questions

Why is the wrong SDK version selected?

Run cjv show active to see which toolchain is currently active and which rule selected it. Then check the selection sources in priority order:

  1. Command-line selectors (+name or --toolchain).
  2. The CJV_TOOLCHAIN environment variable.
  3. Per-directory overrides (cjv override list) and cangjie-sdk.toml files in your current directory and its parent directories. Remember that cjv walks upward one directory level at a time, and an override takes precedence over cangjie-sdk.toml at the same directory level. See Project toolchains.
  4. The global default toolchain (cjv default).

If you evaluated cjv envsetup earlier in the current terminal session, your shell’s PATH points directly to that SDK’s bin/ directory ahead of <CJV_HOME>/bin, bypassing proxy selection. Open a new terminal to restore automatic selection, or run cjv envsetup again for the toolchain you want.

What happens when a field in cangjie-sdk.toml is misspelled?

Unrecognized fields under [toolchain] produce a warning on stderr while recognized fields are still parsed. However, if the remaining fields do not provide a valid channel or path—or if the file is empty or contains invalid TOML syntax—the command fails with an error instead of silently falling back to the global default toolchain. Delete the broken cangjie-sdk.toml file if you want to restore selection from a parent directory or the default toolchain.

My compiled program cannot find runtime libraries

Compiled Cangjie binaries often dynamically link against runtime libraries in the SDK or in stdx. Use cjv exec to run your binary with the active toolchain’s library paths configured automatically:

cjv exec ./my_binary

Alternatively, you can evaluate cjv envsetup in your current shell session so that LD_LIBRARY_PATH (Linux/HarmonyOS), DYLD_LIBRARY_PATH (macOS), or PATH (Windows)—along with CANGJIE_STDX_PATH_DYNAMIC and CANGJIE_STDX_PATH_STATIC—are exported directly into your terminal. See Running commands and setting the environment for shell-specific commands.

How do I install and use cjv offline?

Depending on your environment, you have three options:

  • Pre-populated cache (--offline) — Populate <CJV_HOME>/cache/ on a connected machine with cjv install, copy cache/ and cangjie-sdk.toml to the offline machine, and run with --offline (or CJV_OFFLINE=1). See Automation and JSON interfaces.
  • Local SDK archive or directory — Import local SDK archives with toolchain import or reference unpacked directories with toolchain link. See Custom SDKs.
  • Internal enterprise mirror (dist_server) — Host manifests and archives on an internal distribution server and disable automatic installation and self-update checks in system fallback settings. See Enterprise and offline deployment.

Keep in mind that while installed toolchains run completely locally, any external package dependencies used by cjpm must also be prepared in advance for offline builds.

Why can’t a custom toolchain download components with component add?

A custom toolchain registered by toolchain import or toolchain link has no official release entry, so component add cannot locate its component artifacts. Instead:

  • If you installed the custom toolchain from a local archive or URL, it can automatically install a bundled stdx archive or have a local stdx directory attached via cjv component link stdx /path/to/stdx --toolchain <name>.
  • If you linked an unpacked external SDK directory, that directory is maintained by its owner and cannot be modified with cjv component commands. See Components and offline documentation.

What does uninstall remove?

  • cjv uninstall <name> removes the selected SDK installation, its attached cross-compilation targets, its stdx and offline documentation components, and any directory overrides referring to <name>. If <name> was your global default toolchain, cjv tries to select another installed host toolchain as the default or clears the default setting. External source directories linked via toolchain link or component link are always preserved.
  • cjv self uninstall removes the entire <CJV_HOME> data directory—including all installed toolchains, components, caches, and rollback snapshots—and cleans up PATH. See the Command reference for options.

Why does the macOS download page ask me to choose an architecture?

Many macOS browsers report an Intel (x86_64) User-Agent string even when running on Apple Silicon (arm64) hardware, so a web page cannot always determine your Mac’s native CPU architecture reliably. If you run the install.sh script in your terminal, it detects your native architecture locally. For manual archive downloads, run uname -m in your terminal: arm64 means Apple Silicon and x86_64 means Intel.

What happens when a nightly release has no checksum in nightly.json?

cjv reads nightly versions and download URLs from nightly.json. If an upstream nightly SDK entry temporarily has an empty sha256 field, cjv automatically attempts to fetch <url>.sha256. If that sidecar file has not been published yet, cjv reports the integrity limitation. When operating an internal enterprise mirror, you can compute and write the 64-character SHA-256 directly into nightly.json; see Internal distribution.