Run c3pm from the directory containing project.json or from any directory below it. c3pm finds the project root automatically.

registry, search, show, and toolchain nix also work outside a project.

Command aliases

Short command	Full command
`c3pm add`	`c3pm dep add`
`c3pm remove`	`c3pm dep remove`
`c3pm show`	`c3pm dep show`

Each pair accepts the same arguments and options.

Commands

Command	Purpose
`c3pm list`	List both C3 dependencies and links.
`c3pm dep`	Add, update, list, or remove C3 source dependencies; inspect registry packages and versions.
`c3pm link`	Manage native packages, Nix definitions, and linked C3 library targets.
`c3pm registry`	Add, remove, update, or list package registries.
`c3pm search`	Search locally indexed registry packages.
`c3pm toolchain`	Pin C3 and nixpkgs, and select the user’s Nix backend.
`c3pm install`	Resolve the dependency graph and synchronize generated project state.
`c3pm shell`	Enter the locked environment or run one command inside it.
`c3pm bundle`	Build a portable Linux executable.

Most projects follow this workflow:

configure toolchain → add dependencies/links → install → build/test in shell → bundle

Dependencies

c3pm dep add SOURCE|[NAMESPACE/]NAME[@VERSION] [--rev REF] [--sha256 HASH]
             [--subdir PATH] [--name NAME] [--for-target TARGET]
c3pm dep update [NAMESPACE/]NAME[@VERSION]
c3pm dep update NAME --rev REF|--sha256 HASH
c3pm dep remove NAME [--for-target TARGET]
c3pm dep show [NAMESPACE/]NAME
c3pm dep list [--for-target TARGET]

For a direct source, --rev selects a Git reference, --sha256 supplies an archive’s SRI hash, and --subdir selects its library directory. Registry names use the published source declaration and do not accept these three overrides. Append @VERSION to a registry name to select an exact published version, for example c3pm dep add raylib@5.5. Without it, c3pm uses latest. Use c3pm dep update raylib@6 to change an installed registry package to version 6, or c3pm dep update raylib to use the latest. Registry updates require a recorded registry reference; c3pm does not infer one from a directly added source. To update a direct Git dependency, use its C3 name and --rev REF; for a direct HTTPS archive, use --sha256 HASH. The source location and subdir remain unchanged. --name asserts the expected manifest provides value when adding. --for-target limits a dependency to one project target.

See Search and add packages for accepted source forms and package-name resolution.

List dependencies and links

Command	Shows
`c3pm list`	C3 dependencies and links
`c3pm dep list`	C3 dependencies only
`c3pm link list`	Links only

c3pm list is a combined listing command, not an alias. All three commands accept --for-target TARGET.

For example:

c3pm search raylib
c3pm show vendor/raylib
c3pm list

search and show inspect registries; list shows dependencies and links in the current project.

Links

c3pm link add NAME [--source SOURCE] [--rev REF] [--sha256 HASH]
              [--subdir PATH] [--c3c-target none|TARGET]
              [--nix-package PACKAGE] [--runtime|--passthrough]
              [--for-target TARGET]
c3pm link remove NAME [--for-target TARGET]
c3pm link list [--for-target TARGET]

--nix-package selects a nixpkgs attribute or a path: Nix definition. --c3c-target selects a fetched project’s static or dynamic library target and defaults to none. --runtime is the default propagation mode; --passthrough passes the input to consumers. The two mode flags are mutually exclusive.

See Link libraries and projects for examples and target-specific behavior.

Registries and search

c3pm registry add NAME SOURCE [--rev REF] [--sha256 HASH] [--subdir PATH]
c3pm registry remove NAME
c3pm registry update [NAME]
c3pm registry list
c3pm search [QUERY...] [--registry NAME] [--tag TAG]

registry add and registry update validate and index registries. With no name, update refreshes all configured registries. Search filters the local indexes by query words, registry name, and tag. See Manage registries.

Toolchains

c3pm toolchain show
c3pm toolchain c3c set VERSION
c3pm toolchain c3c reset
c3pm toolchain nixpkgs set REF
c3pm toolchain nixpkgs update
c3pm toolchain nixpkgs reset
c3pm toolchain nix status
c3pm toolchain nix use system|portable|PATH
c3pm toolchain nix reset

The compiler and nixpkgs settings belong to the project. Nix backend selection belongs to the user. See Configure toolchains, including the C3PM_NIX and C3PM_NIX_PORTABLE environment overrides.

Build and ship

c3pm install
c3pm shell [-- COMMAND...]
c3pm bundle [TARGET] [--output PATH]

install synchronizes generated dependencies and Nix state. shell synchronizes first, then opens an interactive shell or runs the command after --. bundle packages an executable target, writing dist/<target> unless --output is supplied.

Help and version

Command	Short form	Purpose
`c3pm --help`	`c3pm -h`	Show the command summary
`c3pm --version`	`c3pm -V`	Show the installed version