CLI reference

Note

ck is an abbreviated alias for the calkit executable. All calkit commands can be run as ck instead, e.g., ck save -am "...".

Top-level commands

Command	Description
init	Initialize the current working directory.
clone	Clone or download a copy of a project.
status\|st	View status (project, version control, and/or pipeline).
diff	Get a unified Git and DVC diff.
add	Add paths to the repo.
commit	Commit a change to the repo.
save\|sv	Save paths by committing and pushing.
pull	Pull with both Git and DVC.
push	Push to Git, DVC, and any Docker registries.
ignore	Ignore a file, i.e., keep it out of version control.
local-server	Run the local server to interact over HTTP.
run	Check requirements and run the pipeline.
manual-step	Execute a manual step.
xenv\|runenv	Execute a command in an environment.
install	Install a registered native dependency (e.g., pixi, uv) via its upstream installer for the current platform.
xproc\|runproc	Execute a procedure.
calc	Run a project's calculation.
set-env-var	Set an environmental variable for the project in its '.env' file.
upgrade	Upgrade Calkit.
switch-branch	Switch to a different branch.
merge	Merge a branch, resolving dvc.lock and stage run records per stage.
stash	Stash or restore workspace changes including dvc-zip tracked dirs.
dvc	Run a command with the DVC CLI.
jupyter	Run a command with the Jupyter CLI.
map-paths	Map paths in a project.
xr	Execute a command and if successful, record in the pipeline.
config	Configure Calkit.
new\|create	Create a new Calkit object.
delete\|rm	Delete a Calkit object.
notebooks\|nb	Work with computational notebooks.
list\|ls	List Calkit objects.
show	Show Calkit objects.
describe\|desc	Describe things.
import	Import objects.
office	Work with Microsoft Office.
update	Update objects.
check	Check things.
fix	Fix things.
latex\|tex	Work with LaTeX.
overleaf\|ol	Interact with Overleaf.
hub\|cloud	Interact with a Calkit hub.
scheduler\|sch	Work with a job scheduler (SLURM or PBS).
sync	Sync with external systems.

Top-level command details

calkit init

Initialize the current working directory.

Usage:

calkit init [OPTIONS]

Options:

Option	Type	Required	Default	Description
--force, -f	boolean	no	False	Re-initialize even if the project is already initialized.
--no-commit	boolean	no	False	Stage the initial files rather than committing them.

calkit clone

Clone or download a copy of a project.

Usage:

calkit clone [OPTIONS] URL [LOCATION]

Arguments:

Argument	Type	Required	Default	Description
url	str	yes		Repo URL.
location	str	no		Location to clone to (default will be ./{repo_name})

Options:

Option	Type	Required	Default	Description
--ssh	boolean	no	False	Use SSH with Git.
--no-config-remote	boolean	no	False	Do not automatically configure Calkit DVC remote.
--no-dvc-pull	boolean	no	False	Do not pull DVC objects.
--no-recursive	boolean	no	False	Do not recursively clone submodules.

calkit status|st

View status (project, version control, and/or pipeline).

Usage:

calkit status|st [OPTIONS] [TARGETS...]

Arguments:

Argument	Type	Required	Default	Description
targets	str	no		Optional targets to check status for. These may be pipeline stage names or repo paths.

Options:

Option	Type	Required	Default	Description
--category, -c	str	no		Status categories to show. By default, all categories are shown. Can be specified multiple times.
--no-env-check	boolean	no	False	Skip environment checks. Note that this may produce an inaccurate pipeline status if materialized environments have changed.
--json	boolean	no	False	Output status as JSON.

calkit diff

Get a unified Git and DVC diff.

Usage:

calkit diff [OPTIONS]

Options:

Option	Type	Required	Default	Description
--staged	boolean	no	False	Show a diff from files staged with Git.

calkit add

Add paths to the repo.

Code will be added to Git and data will be added to DVC.

Note: This will enable the 'autostage' feature of DVC, automatically adding any .dvc files to Git when adding to DVC.

Usage:

calkit add [OPTIONS] PATHS...

Arguments:

Argument	Type	Required	Default	Description
paths	str	yes

Options:

Option	Type	Required	Default	Description
--existing, -e	boolean	no	False	Only add files that already exist in the repo, i.e., don't add any untracked ones.
-m, --commit-message	str	no		Automatically commit and use this as a message.
--auto-message, -M	boolean	no	False	Commit with an automatically-generated message.
--no-auto-ignore	boolean	no	False	Disable auto-ignore.
--push	boolean	no	False	Push after committing.
--to, -t	str	no		System with which to add (git, dvc, or dvc-zip).
--dry-run, --dry	boolean	no	False	Show what would be added without actually adding it.

calkit commit

Commit a change to the repo.

Usage:

calkit commit [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to commit. If not provided, will default to any changed files that have been added previously.

Options:

Option	Type	Required	Default	Description
--all, -a	boolean	no	False	Automatically stage all changed files.
--message, -m	str	no		Commit message.
--auto-commit-message, -M	boolean	no	False	Automatically generate a commit message.
--push	boolean	no	False	Push to both Git and DVC after committing.
--verbose	boolean	no	False	Print verbose output.

calkit save|sv

Save paths by committing and pushing.

This is essentially git/dvc add, commit, and push in one step.

Usage:

calkit save|sv [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to add and commit. If not provided, will default to any changed files that have been added previously.

Options:

Option	Type	Required	Default	Description
--all, -a	boolean	no	False	Save all, automatically handling staging and ignoring.
--existing, -e	boolean	no	False	Only save files that already exist in the repo, i.e., don't automatically add new ones.
--message, -m	str	no		Commit message.
--auto-message, -M	boolean	no	False	Commit with an automatically-generated message.
--to, -t	str	no		System with which to add (git or dvc).
--no-push	boolean	no	False	Do not push to Git and DVC after committing.
--git-push	str	no		Additional Git args to pass when pushing.
--dvc-push	str	no		Additional DVC args to pass when pushing.
--no-recursive	boolean	no	False	Do not push to submodules.
--overleaf, -O	boolean	no	False	Sync with Overleaf after saving.
--verbose, -v	boolean	no	False	Print verbose output.
--dry-run, --dry	boolean	no	False	Show what would be saved without actually saving it.

calkit pull

Pull with both Git and DVC.

Usage:

calkit pull [OPTIONS]

Options:

Option	Type	Required	Default	Description
--no-check-auth	boolean	no	False
--no-dvc	boolean	no	False	Do not pull from DVC.
--no-git	boolean	no	False	Do not pull from Git.
--git-arg	str	no		Additional Git args.
--dvc-arg	str	no		Additional DVC args.
--force, -f	boolean	no	False	Force pull, potentially overwriting local changes.
--no-recursive	boolean	no	False	Do not recursively pull from submodules.

calkit push

Push to Git, DVC, and any Docker registries.

Usage:

calkit push [OPTIONS] [TARGETS...]

Arguments:

Argument	Type	Required	Default	Description
targets	str	no		What to push: 'git', 'dvc', 'docker', or 'all'. Defaults to all.

Options:

Option	Type	Required	Default	Description
--no-check-auth	boolean	no	False	Do not check DVC remote authentication.
--no-dvc	boolean	no	False	Do not push to DVC remotes.
--no-git	boolean	no	False	Do not push to Git remote.
--git-arg	str	no		Additional Git args.
--dvc-arg	str	no		Additional DVC args.
--no-docker	boolean	no	False	Do not push Docker images to their registries.
--no-recursive	boolean	no	False	Do not push to submodules.

calkit ignore

Ignore a file, i.e., keep it out of version control.

Usage:

calkit ignore [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path to ignore.

Options:

Option	Type	Required	Default	Description
--no-commit	boolean	no	False	Do not commit changes to .gitignore.

calkit local-server

Run the local server to interact over HTTP.

Usage:

calkit local-server

calkit run

Check requirements and run the pipeline.

Usage:

calkit run [OPTIONS] [TARGETS...]

Arguments:

Argument	Type	Required	Default	Description
targets	str	no		Stages to run.

Options:

Option	Type	Required	Default	Description
-q, --quiet	boolean	no	False	Be quiet.
-v, --verbose	boolean	no	False	Print verbose output.
-f, --force	boolean	no	False	Run even if stages or inputs have not changed.
-i, --interactive	boolean	no	False	Ask for confirmation before running each stage.
-s, --single-item	boolean	no	False	Run only a single stage without any dependents.
-p, --pipeline	str	no
-P, --all-pipelines	boolean	no	False	Run all pipelines in the repo.
-R, --recursive	boolean	no	False	Run pipelines in subdirectories.
--downstream	str	no		Start from the specified stage and run all downstream.
--force-downstream	boolean	no	False	Force downstream stages to run even if they are still up-to-date.
--pull	boolean	no	False	Try automatically pulling missing data.
--allow-missing	boolean	no	False	Skip stages with missing data.
--dry, --dry-run	boolean	no	False	Only print commands that would execute.
--keep-going, -k	boolean	no	False	Continue executing, skipping stages with failed inputs from other stages.
--ignore-errors	boolean	no	False	Ignore errors from stages.
--glob	boolean	no	False	Match stages with glob-style patterns.
--no-commit	boolean	no	False	Do not save to the run cache.
--no-run-cache	boolean	no	False	Ignore the run cache.
--log, -l	boolean	no	False	Log the run and system information.
--save, -S	boolean	no	False	Save the project after running.
--save-message, -m	str	no		Commit message for saving.
--input, --dep	str	no		Run stages that depend on given input dependency path.
--output, --out	str	no		Run stages that produce the given output path.
--overleaf, -O	boolean	no	False	Sync with Overleaf before and after running.
--no-push	boolean	no	False	Do not push to Git and DVC after saving.
--mock-scheduler, -K	boolean	no	False	Run job-scheduler (SLURM/PBS) stages locally instead of submitting them to a real scheduler.
--strict	boolean	no	False	Fail if an out-of-date stage can't run on this machine rather than skipping it, e.g., in CI for a project whose stages should all run there.

calkit manual-step

Execute a manual step.

Usage:

calkit manual-step [OPTIONS]

Options:

Option	Type	Required	Default	Description
--message, -m	str	yes		Message to display as a prompt.
--cmd	str	no		Command to run.
--show-stdout	boolean	no	False	Show stdout.
--show-stderr	boolean	no	False	Show stderr.

calkit xenv|runenv

Execute a command in an environment.

Usage:

calkit xenv|runenv [OPTIONS] CMD...

Arguments:

Argument	Type	Required	Default	Description
cmd	str	yes		Command to run in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	no		Environment name in which to run. Only necessary if there are multiple in this project and path is not provided.
--env-path, -p	str	no		Path of spec of environment in which to run. Will be added to the project if it doesn't exist.
--wdir	str	no		Working directory. By default will run current working directory.
--no-check	boolean	no	False	Don't check the environment is valid before running in it.
--relaxed	boolean	no	False	Check the environment in a relaxed way, if applicable.
--setup	str	no		Shell command to run before the command, in the same shell (repeat for multiple). A pipeline stage gets these from its own 'setup' and its environment's 'default_setup', already combined when the pipeline is compiled.
--setup-file	str	no		Path to a JSON list of setup commands, used instead of --setup. This is what a compiled pipeline stage carries, since a path survives being parsed by cmd.exe on Windows and by a POSIX shell elsewhere, and quoted commands don't.
--env-var	str	no		Environmental variable to set for the command, as KEY=VALUE. Can be given multiple times. Set in the process the command runs in, and passed into a container for an environment that runs in one.
--verbose, -v	boolean	no	False	Print verbose output.

calkit install

Install a registered native dependency (e.g., pixi, uv) via its upstream installer for the current platform.

Usage:

calkit install [OPTIONS] NAME

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		The app to install (e.g., 'pixi', 'uv').

Options:

Option	Type	Required	Default	Description
--yes, -y	boolean	no	False	Skip the confirmation prompt and install immediately.

calkit xproc|runproc

Execute a procedure.

Usage:

calkit xproc|runproc [OPTIONS] NAME

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		The name of the procedure.

Options:

Option	Type	Required	Default	Description
--no-commit	boolean	no	False	Do not commit after each action.

calkit calc

Run a project's calculation.

Usage:

calkit calc [OPTIONS] NAME

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		Calculation name.

Options:

Option	Type	Required	Default	Description
--input, -i	str	no		Inputs defined like x=1 (with no spaces.)
--no-format	boolean	no	False	Do not format output before printing

calkit set-env-var

Set an environmental variable for the project in its '.env' file.

Usage:

calkit set-env-var NAME VALUE

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		Name of the variable.
value	str	yes		Value of the variable.

calkit upgrade

Upgrade Calkit.

A dev (editable) install is updated from the branch it's on, as with 'calkit dev upgrade'.

Usage:

calkit upgrade [OPTIONS]

Options:

Option	Type	Required	Default	Description
--skills	boolean	no	False	Upgrade agent skills as well.

calkit switch-branch

Switch to a different branch.

Usage:

calkit switch-branch NAME

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		Branch name.

calkit merge

Merge a branch, resolving dvc.lock and stage run records per stage.

A stage changed on both sides needs a choice: ours, theirs, or rerun, which also decides its run record and Git-tracked outputs. DVC-tracked outputs are checked out to match afterwards. Other conflicts are left to resolve before 'calkit merge --continue'.

Usage:

calkit merge [OPTIONS] [BRANCH]

Arguments:

Argument	Type	Required	Default	Description
branch	str	no		Branch or commit to merge into the current one.

Options:

Option	Type	Required	Default	Description
--continue	boolean	no	False	Finish a merge stopped by conflicts.
--abort	boolean	no	False	Abort the merge in progress.
--squash	boolean	no	False	Combine the branch's changes into one commit.
--message, -m	str	no		Commit message (default: Git's for the merge or squash).
--ours, -o	str	no		Keep our side of this stage (repeatable).
--theirs, -t	str	no		Keep their side of this stage (repeatable).
--rerun, -r	str	no		Keep neither side of this stage, so it reruns (repeatable).
--prefer	str	no		Choice for every other stage changed on both sides (ours, theirs, or rerun).
--git-arg	str	no		Additional Git merge args.

calkit stash

Stash or restore workspace changes including dvc-zip tracked dirs.

Without --pop: zips any modified workspace dirs and commits any other modified DVC-tracked paths into the DVC cache, then git-stashes (saving the updated .dvc files and dvc.lock), checks out the committed DVC state, and unzips it to the workspace.

With --pop: pops the git stash (restoring the saved .dvc files), checks out the stashed DVC state, and unzips it to the workspace.

Usage:

calkit stash [OPTIONS]

Options:

Option	Type	Required	Default	Description
--pop	boolean	no	False	Pop the most recent stash.

calkit dvc

Run a command with the DVC CLI.

Useful if Calkit is installed as a tool, e.g., with uv tool or pipx, and DVC is not installed.

Usage:

calkit dvc [OPTIONS]

calkit jupyter

Run a command with the Jupyter CLI.

Usage:

calkit jupyter [OPTIONS]

calkit map-paths

Map paths in a project.

Currently this is done with copying. Outputs are ensured to be ignored by Git.

Usage:

calkit map-paths [OPTIONS]

Options:

Option	Type	Required	Default	Description
--file-to-file	str	no		Map a file to another file, e.g., --file-to-file 'results.tex->paper/results.tex'.
--file-to-dir	str	no		Map a file into a directory, e.g., --file-to-dir 'results.tex->paper/results'.
--dir-to-dir-replace	str	no		Copy directory to another directory and replace it, e.g., --dir-to-dir-replace 'figures->paper/figures'.
--dir-to-dir-merge	str	no		Merge directory into another directory. This is useful for merging contents of one directory into another, e.g., --dir-to-dir-merge 'figures->paper/figures'.

calkit xr

Execute a command and if successful, record in the pipeline.

Usage:

calkit xr [OPTIONS] CMD...

Arguments:

Argument	Type	Required	Default	Description
cmd	str	yes		Command to execute and record. If the first argument is a script, notebook or LaTeX file, it will be treated as a stage with that file as the target. Any command, including arguments, is supported.

Options:

Option	Type	Required	Default	Description
--environment, -e	str	no		Name of or path the spec file for the environment to use.
--input, -i	str	no		Input paths to record.
--output, -o	str	no		Output paths to record.
--no-detect-io	boolean	no	False	Don't attempt to detect inputs and outputs from the command, script, or notebook.
--stage	str	no		Name of the DVC stage to create for this command. If not provided, a name will be generated automatically.
--dry-run, -d	boolean	no	False	Print the environment and stage that would be created without modifying calkit.yaml or executing the command.
--no-record	boolean	no	False	Execute without recording: run as usual, then restore calkit.yaml, dvc.yaml and .dvc and remove derived files, keeping only what the run produced (annotations, injected output, stage outputs) and the run log. Useful for checking that a Markdown file is runnable in a project that isn't a Calkit project.
--json	boolean	no	False	Print xr results as JSON.
--force, -f	boolean	no	False	Force running stage even if it's up-to-date.
--verbose, -v	boolean	no	False	Print verbose output.

Command groups

calkit config

Configure Calkit.

Command	Description
set	Set a value in the config.
get	Get and print a value from the config.
unset	Unset a value in the config, returning it to default.
remote	Set up the Calkit hub as the default DVC remote and store a token in the local config.
remote-auth	Store a Calkit hub token in the local DVC config for all Calkit remotes.
list	List keys in the config.
github-ssh	Walk through the process of adding an SSH key to GitHub.
github-codespace	Configure a GitHub Codespace.

calkit config set

Set a value in the config.

Usage:

calkit config set KEY VALUE

Arguments:

Argument	Type	Required	Default	Description
key	str	yes
value	str	yes

calkit config get

Get and print a value from the config.

Usage:

calkit config get KEY

Arguments:

Argument	Type	Required	Default	Description
key	str	yes

calkit config unset

Unset a value in the config, returning it to default.

Usage:

calkit config unset KEY

Arguments:

Argument	Type	Required	Default	Description
key	str	yes

calkit config remote

Set up the Calkit hub as the default DVC remote and store a token in the local config.

Deprecated: this configures the project, not Calkit itself, which is what the rest of this app is for.

Usage:

calkit config remote [OPTIONS]

Options:

Option	Type	Required	Default	Description
--http	boolean	no	False	Use the legacy HTTP URL for the Calkit DVC remote instead of ck://.
--no-commit	boolean	no	False	Do not commit changes to DVC config.

calkit config remote-auth

Store a Calkit hub token in the local DVC config for all Calkit remotes.

Usage:

calkit config remote-auth

calkit config list

List keys in the config.

Usage:

calkit config list

calkit config github-ssh

Walk through the process of adding an SSH key to GitHub.

Usage:

calkit config github-ssh

calkit config github-codespace

Configure a GitHub Codespace.

Typically this will simply mean we exchange a GitHub token for a Calkit token to use for pushing with DVC.

If this is run outside a Codespace, typically nothing will happen.

Usage:

calkit config github-codespace

calkit new|create

Create a new Calkit object.

Command	Description
project	Create a new project.
figure\|fig	Create a new figure.
result	Declare a new result.
presentation\|pres	Declare a new presentation.
question	Add a new question.
comment	Start a review comment thread above a paragraph of a LaTeX or Markdown document, printing its ID.
notebook\|nb	Add a new notebook.
docker-env	Create a new Docker environment.
foreach-stage	Create a new DVC 'foreach' stage.
dataset	Create a new dataset.
publication\|pub	Create a new publication.
conda-env	Create a new Conda environment.
uv-env	Create a new uv project environment.
slurm-env	Create a new SLURM environment.
pbs-env	Create a new PBS environment.
uv-venv	Create a new uv virtual environment.
venv	Create a new Python virtual environment with venv.
pixi-env	Create a new pixi virtual environment.
julia-env	Create a new Julia environment or add an existing one to calkit.yaml.
renv	Create a new R environment with renv.
nix-env	Create a new Nix flake-based environment.
status	Add a new project status to the log.
python-script-stage	Add a stage to the pipeline that runs a Python script.
julia-script-stage	Add a stage to the pipeline that runs a Julia script.
matlab-script-stage	Add a stage to the pipeline that runs a MATLAB script.
latex-stage	Add a stage to the pipeline that compiles a LaTeX document.
jupyter-notebook-stage	Add a stage to the pipeline that runs a Jupyter notebook.
release	Create a new release.

calkit new|create project

Create a new project.

Usage:

calkit new|create project [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Where to create the project.

Options:

Option	Type	Required	Default	Description
--name, -n	str	no		Project name. Will be inferred as kebab-cased directory name if not provided.
--title	str	no		Project title.
--description	str	no		Project description.
--hub, --cloud	str	no		Create this project on a Calkit hub (and GitHub). Optionally takes a hub URL; bare --hub (or the special value 'default') uses the default_hub config value, else calkit.io. --cloud is a deprecated alias.
--public	boolean	no	False	Create as a public project if --hub is selected.
--git-url	str	no		Git repo URL. Usually https://github.com/{your_name}/{project_name}.
--template, --from, -t	str	no		Template from which to derive the project: a hub project as 'owner/project' or its hub URL, or a Git URL on any host, e.g., 'https://github.com/owner/repo/dir'.
--no-commit	boolean	no		Do not commit changes to Git.
--overwrite, -f	boolean	no	False	Overwrite project if one already exists.
--verbose	boolean	no	False	Print verbose output.

calkit new|create figure|fig

Create a new figure.

Usage:

calkit new|create figure|fig [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--title	str	yes
--description	str	yes
--stage	str	no		Name of the pipeline stage that generates this figure.
--cmd	str	no		Command to add to the stage, if specified.
--dep	str	no		Path to stage dependency.
--out	str	no		Path to stage output. Figure path will be added automatically.
--deps-from-stage-outs	str	no		Stage name from which to add outputs as dependencies.
--created-by-email	str	no		Email of whoever made this figure, for one drawn by hand rather than produced by a stage.
--created-by-orcid	str	no		ORCID of whoever made this figure.
--created-with-ai	str	no		Generative AI tool they used, e.g. 'Claude Opus 5'. Repeat for several.
--no-commit	boolean	no	False
--overwrite, -f	boolean	no	False	Overwrite existing figure if one exists.

calkit new|create result

Declare a new result.

Usage:

calkit new|create result [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--name	str	no		Short handle for referring to this result, which stays stable if the file is renamed.
--title	str	no
--key	str	no		Path to the value within the file, e.g., 'metrics.mean'. Omit if the whole file is the result.
--description	str	no
--stage	str	no		Name of the pipeline stage that generates this result.
--no-commit	boolean	no	False
--overwrite, -f	boolean	no	False	Overwrite existing result if one exists.

calkit new|create presentation|pres

Declare a new presentation.

Usage:

calkit new|create presentation|pres [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--title	str	yes
--description	str	no
--kind	str	no		Kind of presentation, either 'slides' or 'poster'.
--stage	str	no		Name of the pipeline stage that generates this presentation.
--no-commit	boolean	no	False
--overwrite, -f	boolean	no	False	Overwrite existing presentation if one exists.

calkit new|create question

Add a new question.

Usage:

calkit new|create question [OPTIONS] QUESTION

Arguments:

Argument	Type	Required	Default	Description
question	str	yes

Options:

Option	Type	Required	Default	Description
--commit	boolean	no	False

calkit new|create comment

Start a review comment thread above a paragraph of a LaTeX or Markdown document, printing its ID.

Usage:

calkit new|create comment [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		File to comment in.

Options:

Option	Type	Required	Default	Description
--line, -l	int	yes		A line in, or just above, the paragraph to comment on.
--text, -m	str	yes		The comment.
--highlight	str	no		Rendered text in the paragraph it's about.
--occ	int	no	0	Which occurrence of the highlight text, from 0.
--author	str	no		Defaults to Git's user.name.
--email	str	no		Defaults to Git's user.email.
--json	boolean	no	False	Output the thread as JSON.

calkit new|create notebook|nb

Add a new notebook.

Usage:

calkit new|create notebook|nb [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Notebook path (relative)

Options:

Option	Type	Required	Default	Description
--title	str	yes
--description	str	no
--stage	str	no		Name of the pipeline stage that runs this notebook.
--commit	boolean	no	False

calkit new|create docker-env

Create a new Docker environment.

Usage:

calkit new|create docker-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--image	str	no		Image identifier. Should be unique and descriptive. Will default to environment name if not specified.
--from	str	no		Base image, e.g., 'ubuntu', if creating a Dockerfile.
--path	str	no		Dockerfile path. Will default to 'Dockerfile' if --from is specified.
--add-layer	str	no		Add a layer (options: miniforge, foampy, uv, julia).
--env-var	str	no		Environment variables to set in the container.
--gpus	str	no
--arg	str	no		Arguments to use when running container.
--input, --dep	str	no		Path to a file that gets added to the container, so editing it rebuilds the image.
--wdir	str	no	/work	Working directory.
--command-mode	str	no	shell	How to execute commands in the container: 'shell' runs shell -c, 'entrypoint' passes args directly to the image entrypoint.
--user	str	no		User account to use to run the container.
--platform	str	no		Platform to pull and run the image as, e.g., 'linux/amd64'.
--registry	str	no		Registry prefix to push built images to and pull them from instead of rebuilding, e.g., 'ghcr.io/someone/some-project', or 'ghcr.io' for the project's own namespace in the GitHub Container Registry.
--platform-build	str	no		Platform to build the image for, as opposed to --platform, which is the one it's pulled and run as. Repeat for a multi-platform image, which requires a registry.
--port	str	no		Ports to expose in the container, e.g., '8080:80'. Can be specified multiple times.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create foreach-stage

Create a new DVC 'foreach' stage.

The list of values must be a simple list. For more complex objects, edit dvc.yaml directly.

Usage:

calkit new|create foreach-stage [OPTIONS] VALS...

Arguments:

Argument	Type	Required	Default	Description
vals	str	yes		Values to iterate over

Options:

Option	Type	Required	Default	Description
--cmd	str	yes		Command to run. Can include {var} to fill with variable.
--name, -n	str	yes		Stage name.
--dep	str	no		Path to add as a dependency.
--out	str	no		Path to add as an output.
--overwrite, -f	boolean	no	False	Overwrite stage if one already exists.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create dataset

Create a new dataset.

Usage:

calkit new|create dataset [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--title	str	yes
--description	str	yes
--stage	str	no		Name of the pipeline stage that generates this dataset.
--cmd	str	no		Command to add to the stage, if specified.
--dep	str	no		Path to stage dependency.
--out	str	no		Path to stage output. Dataset path will be added automatically.
--deps-from-stage-outs	str	no		Stage name from which to add outputs as dependencies.
--created-by-email	str	no		Email of whoever collected this data for the project, which marks it as primary rather than imported or computed.
--created-by-orcid	str	no		ORCID of whoever collected this data.
--created-with-ai	str	no		Generative AI tool they used, e.g. 'Claude Opus 5'. Repeat for several.
--no-commit	boolean	no	False
--overwrite, -f	boolean	no	False	Overwrite existing dataset if one exists.

calkit new|create publication|pub

Create a new publication.

Usage:

calkit new|create publication|pub [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path for the publication. If using a template, this could be a directory.

Options:

Option	Type	Required	Default	Description
--title	str	yes		The title of the publication.
--kind	str	yes		Kind of the publication, e.g., 'journal-article'.
--description	str	no		A description of the publication.
--stage	str	no		Name of the pipeline stage to build the output file.
--dep	str	no		Path to stage dependency.
--deps-from-stage-outs	str	no		Stage name from which to add outputs as dependencies.
--template, -t	str	no		Template with which to create the source files. Should be in the format {type}/{name}.
--environment	str	no		Name of the build environment to create, if desired.
--no-commit	boolean	no	False	Do not commit resulting changes to the repo.
--overwrite, -f	boolean	no	False	Overwrite existing objects if they already exist.

calkit new|create conda-env

Create a new Conda environment.

Usage:

calkit new|create conda-env [OPTIONS] [PACKAGES...]

Arguments:

Argument	Type	Required	Default	Description
packages	str	no		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--conda-name	str	no		Name to use in the Conda environment file, if desired. Will be automatically generated if not provided. Note that these should be unique since Conda environments are a system-wide collection.
--path	str	no	environment.yml	Environment YAML file path.
--pip	str	no		Packages to install with pip.
--prefix	str	no		Prefix for environment location.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create uv-env

Create a new uv project environment.

Usage:

calkit new|create uv-env [OPTIONS] [PACKAGES...]

Arguments:

Argument	Type	Required	Default	Description
packages	str	no		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	no	main	Environment name.
--path	str	no		Environment file path. Must end with 'pyproject.toml'.
--python, -p	str	no		Python version.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create slurm-env

Create a new SLURM environment.

Usage:

calkit new|create slurm-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--host	str	no	localhost	Host where SLURM commands should run.
--default-option	str	no		Default sbatch/srun option string (for example --gpus=1). Repeat for multiple options.
--default-setup	str	no		Default shell setup command to run before SLURM jobs (for example 'module load julia/1.11'). Repeat for multiple commands.
--max-concurrent-jobs	int	no		Maximum number of this project's jobs allowed in the queue at once, or 0 for no limit. Submissions beyond this wait for a slot, so an iterated stage does not take over a shared cluster's queue. Unlimited by default.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create pbs-env

Create a new PBS environment.

Usage:

calkit new|create pbs-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--host	str	no	localhost	Host where PBS commands should run.
--default-option	str	no		Default qsub option string (for example --default-option=-l --default-option=walltime=01:00:00). Repeat for multiple options.
--default-setup	str	no		Default shell setup command to run before PBS jobs (for example 'module load julia/1.11'). Repeat for multiple commands.
--max-concurrent-jobs	int	no		Maximum number of this project's jobs allowed in the queue at once, or 0 for no limit. Submissions beyond this wait for a slot, so an iterated stage does not take over a shared cluster's queue. Unlimited by default.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create uv-venv

Create a new uv virtual environment.

Usage:

calkit new|create uv-venv [OPTIONS] [PACKAGES...]

Arguments:

Argument	Type	Required	Default	Description
packages	str	no		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--path	str	no	requirements.txt	Path for requirements file.
--prefix	str	no		Prefix for environment location (defaults to .venv, or .calkit/envs//.venv if .venv is already taken).
--python, -p	str	no		Python version.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create venv

Create a new Python virtual environment with venv.

Usage:

calkit new|create venv [OPTIONS] PACKAGES...

Arguments:

Argument	Type	Required	Default	Description
packages	str	yes		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--path	str	no	requirements.txt	Path for requirements file.
--prefix	str	no		Prefix for environment location (defaults to .venv, or .calkit/envs//.venv if .venv is already taken).
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create pixi-env

Create a new pixi virtual environment.

Usage:

calkit new|create pixi-env [OPTIONS] PACKAGES...

Arguments:

Argument	Type	Required	Default	Description
packages	str	yes		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--pip	str	no		Packages to install with pip.
--description	str	no		Description.
--platform, -p	str	no		Platform.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create julia-env

Create a new Julia environment or add an existing one to calkit.yaml.

Usage:

calkit new|create julia-env [OPTIONS] [PACKAGES...]

Arguments:

Argument	Type	Required	Default	Description
packages	str	no		Optional packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	no	main	Environment name.
--path	str	no		Path for Project.toml file.
--description	str	no		Description.
--julia, -j	str	no		Julia version. Auto-detected if not supplied.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-commit	boolean	no	False	Do not commit changes.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.

calkit new|create renv

Create a new R environment with renv.

Usage:

calkit new|create renv [OPTIONS] [PACKAGES...]

Arguments:

Argument	Type	Required	Default	Description
packages	str	no		Packages to include in the environment.

Options:

Option	Type	Required	Default	Description
--name, -n	str	no	main	Environment name.
--path	str	no		Environment file path. Must end with 'DESCRIPTION'.
--r-version, -r	str	no		R version.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-check	boolean	no	False	Do not check environment is up-to-date after creation.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create nix-env

Create a new Nix flake-based environment.

Usage:

calkit new|create nix-env [OPTIONS] PACKAGES...

Arguments:

Argument	Type	Required	Default	Description
packages	str	yes		Nixpkgs packages to include in the dev shell (e.g. R).

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--path	str	no		Flake file path. Must end with 'flake.nix'.
--nixpkgs-url	str	no	github:NixOS/nixpkgs/nixos-unstable	Flake input URL for nixpkgs.
--description	str	no		Description.
--overwrite, -f	boolean	no	False	Overwrite any existing environment with this name.
--no-check	boolean	no	False	Do not run 'nix flake lock' after creating the flake.
--no-commit	boolean	no	False	Do not commit changes.

calkit new|create status

Add a new project status to the log.

Usage:

calkit new|create status [OPTIONS] STATUS

Arguments:

Argument	Type	Required	Default	Description
status	choice(in-progress, on-hold, completed)	yes		Current status of the project.

Options:

Option	Type	Required	Default	Description
--message, -m	str	no		Optional message describing the status.
--no-commit	boolean	no	False	Do not commit changes to the status log.

calkit new|create python-script-stage

Add a stage to the pipeline that runs a Python script.

Usage:

calkit new|create python-script-stage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Stage name, typically kebab-case.
--environment, -e	str	yes		Environment to use to run the stage.
--script-path, -s	str	yes		Path to script.
--arg	str	no		Argument to pass to the script.
--input, -i	str	no		A path on which the stage depends.
--output, -o	str	no		A path that is produced by the stage.
--out-git	str	no		An output that should be stored with Git instead of DVC.
--out-git-no-delete	str	no		An output that should be tracked with Git instead of DVC, and also should not be deleted before running stage.
--out-no-delete	str	no		An output that should not be deleted before running.
--out-no-store	str	no		An output that should not be stored in version control.
--out-no-store-no-delete	str	no		An output that should not be stored in version control, and should not be deleted before running.
--iter		no		Iterate over an argument with a comma-separated list, e.g., --iter-arg var_name val1,val2,val3.
--overwrite, --force, -f	boolean	no	False	Overwrite an existing stage with this name if necessary.
--no-check	boolean	no	False	Do not check if the target, deps, environment, etc., exist.
--no-commit	boolean	no	False	Do not commit changes to Git.

calkit new|create julia-script-stage

Add a stage to the pipeline that runs a Julia script.

Usage:

calkit new|create julia-script-stage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Stage name, typically kebab-case.
--environment, -e	str	yes		Environment to use to run the stage.
--script-path, -s	str	yes		Path to script.
--input, -i	str	no		A path on which the stage depends.
--output, -o	str	no		A path that is produced by the stage.
--out-git	str	no		An output that should be stored with Git instead of DVC.
--out-git-no-delete	str	no		An output that should be tracked with Git instead of DVC, and also should not be deleted before running stage.
--out-no-delete	str	no		An output that should not be deleted before running.
--out-no-store	str	no		An output that should not be stored in version control.
--out-no-store-no-delete	str	no		An output that should not be stored in version control, and should not be deleted before running.
--iter		no		Iterate over an argument with a comma-separated list, e.g., --iter-arg var_name val1,val2,val3.
--overwrite, --force, -f	boolean	no	False	Overwrite an existing stage with this name if necessary.
--no-check	boolean	no	False	Do not check if the target, deps, environment, etc., exist.
--no-commit	boolean	no	False	Do not commit changes to Git.

calkit new|create matlab-script-stage

Add a stage to the pipeline that runs a MATLAB script.

Usage:

calkit new|create matlab-script-stage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Stage name, typically kebab-case.
--environment, -e	str	yes		Environment to use to run the stage.
--script-path, -s	str	yes		Path to script.
--input, -i	str	no		A path on which the stage depends.
--output, -o	str	no		A path that is produced by the stage.
--out-git	str	no		An output that should be stored with Git instead of DVC.
--out-git-no-delete	str	no		An output that should be tracked with Git instead of DVC, and also should not be deleted before running stage.
--out-no-delete	str	no		An output that should not be deleted before running.
--out-no-store	str	no		An output that should not be stored in version control.
--out-no-store-no-delete	str	no		An output that should not be stored in version control, and should not be deleted before running.
--overwrite, --force, -f	boolean	no	False	Overwrite an existing stage with this name if necessary.
--no-check	boolean	no	False	Do not check if the target, deps, environment, etc., exist.
--no-commit	boolean	no	False	Do not commit changes to Git.

calkit new|create latex-stage

Add a stage to the pipeline that compiles a LaTeX document.

Usage:

calkit new|create latex-stage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Stage name, typically kebab-case.
--environment, -e	str	yes		Environment to use to run the stage.
--target	str	yes		Target .tex file path.
--output-dir	str	no		Directory for the compiled PDF (passed to latexmk as -outdir). Ignored when a latexmkrc is provided.
--aux-dir	str	no		Directory for auxiliary files (passed to latexmk as -auxdir). Ignored when a latexmkrc is provided.
--latexmkrc	str	no		Path to a latexmkrc file for compilation.
--latexmk-arg	str	no		Extra argument passed through to latexmk. Repeat the option to pass more than one.
--input, -i	str	no		A path on which the stage depends.
--no-detect-inputs	boolean	no	False	Don't add the class, style, bibliography, and figure files the document reads as inputs.
--output, -o	str	no		A path that is produced by the stage.
--out-git	str	no		An output that should be stored with Git instead of DVC.
--out-git-no-delete	str	no		An output that should be tracked with Git instead of DVC, and also should not be deleted before running stage.
--out-no-delete	str	no		An output that should not be deleted before running.
--out-no-store	str	no		An output that should not be stored in version control.
--out-no-store-no-delete	str	no		An output that should not be stored in version control, and should not be deleted before running.
--overwrite, --force, -f	boolean	no	False	Overwrite an existing stage with this name if necessary.
--no-check	boolean	no	False	Do not check if the target, deps, environment, etc., exist.
--no-commit	boolean	no	False	Do not commit changes to Git.

calkit new|create jupyter-notebook-stage

Add a stage to the pipeline that runs a Jupyter notebook.

Usage:

calkit new|create jupyter-notebook-stage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Stage name, typically kebab-case.
--environment, -e	str	yes		Environment to use to run the stage.
--notebook-path	str	yes		Path to notebook.
--input, -i	str	no		A path on which the stage depends.
--output, -o	str	no		A path that is produced by the stage.
--out-git	str	no		An output that should be stored with Git instead of DVC.
--out-git-no-delete	str	no		An output that should be tracked with Git instead of DVC, and also should not be deleted before running stage.
--out-no-delete	str	no		An output that should not be deleted before running.
--out-no-store	str	no		An output that should not be stored in version control.
--out-no-store-no-delete	str	no		An output that should not be stored in version control, and should not be deleted before running.
--html-storage	choice(git, dvc, None)	no	dvc	In what system to store the HTML output of the notebook.
--cleaned-ipynb-storage	choice(git, dvc, None)	no	git	In what system to store the cleaned ipynb output of the notebook.
--executed-ipynb-storage	choice(git, dvc, None)	no	dvc	In what system to store the executed ipynb output of the notebook.
--overwrite, --force, -f	boolean	no	False	Overwrite an existing stage with this name if necessary.
--no-check	boolean	no	False	Do not check if the target, deps, environment, etc., exist.
--no-commit	boolean	no	False	Do not commit changes to Git.

calkit new|create release

Create a new release.

Usage:

calkit new|create release [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no	.	The path to release; '.' for a project release.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		A name for the release, typically kebab-case or a semantic version. Will be used for the Git tag and GitHub release title.
--kind	str	no		What kind of release to create. Will attempt to infer from path if not provided.
--description, --desc	str	no		A description of the release. Will be auto-generated if not provided.
--date	str	no		Release date. Will default to today.
--pipeline	boolean	no	False	Include everything needed to reproduce the released path, i.e., the pipeline, its lock file, and the stages, inputs, and environments the path depends on. Stages unrelated to the path are left out.
--no-docker-images	boolean	no	False	Do not archive the project's Docker images in the release.
--dry-run	boolean	no	False	Only print actions that would be taken but don't take them.
--no-commit	boolean	no	False	Do not commit changes to Git repo.
--no-push	boolean	no	False	Do not push to Git remote.
--internal	boolean	no	False	Create an internal release that is not published to an archival service. Still creates a Git tag and release record in calkit.yaml, but does not upload files or create a GitHub release.
--no-github	boolean	no	False	Do not create a GitHub release.
--to	str	no	zenodo	Archival service to use for external releases (zenodo or caltechdata); ignored for --internal releases.
--draft	boolean	no	False	Create draft record with reserved DOI but do not publish.
--license	str	no		License ID (from https://spdx.org/licenses). Multiple can be specified. Will try to infer from LICENSE file, if present.
--verbose, -v	boolean	no	False	Print verbose output.

calkit delete|rm

Delete a Calkit object.

Command	Description
question	Remove a question by its 1-based index.
comment	Delete a review comment thread and its replies.

calkit delete|rm question

Remove a question by its 1-based index.

Usage:

calkit delete|rm question INDEX

Arguments:

Argument	Type	Required	Default	Description
index	int	yes		1-based index of the question to remove (see calkit list questions).

calkit delete|rm comment

Delete a review comment thread and its replies.

Usage:

calkit delete|rm comment [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no		File the thread is in, if not found by --id.

Options:

Option	Type	Required	Default	Description
--id	str	no		ID of the thread, which finds it in any of the project's documents.
--line, -l	int	no		Number of any line in the thread.

calkit notebooks|nb

Work with computational notebooks.

Command	Description
clean	Clean notebook and place a copy in the cleaned notebooks directory.
clean-all	Clean all notebooks in the pipeline.
check-kernel	Check that an environment has a registered Jupyter kernel.
execute	Execute notebook and place a copy in the relevant directory.
export-marimo-wasm	Export a marimo notebook to a WebAssembly app.

calkit notebooks|nb clean

Clean notebook and place a copy in the cleaned notebooks directory.

This can be useful to use as a preprocessing DVC stage to use a clean notebook as a dependency for a stage that caches and executed notebook.

Usage:

calkit notebooks|nb clean [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--quiet, -q	boolean	no	False	Do not print output.

calkit notebooks|nb clean-all

Clean all notebooks in the pipeline.

Usage:

calkit notebooks|nb clean-all [OPTIONS]

Options:

Option	Type	Required	Default	Description
--quiet, -q	boolean	no	False	Do not print output.

calkit notebooks|nb check-kernel

Check that an environment has a registered Jupyter kernel.

Usage:

calkit notebooks|nb check-kernel [OPTIONS]

Options:

Option	Type	Required	Default	Description
--environment, --env, -e	str	yes		Environment name in which to run the notebook.
--no-check	boolean	no	False	Do not check environment before executing.
--language, -l	str	no		Notebook language; if 'matlab', MATLAB kernel must be available in environment.
--verbose, -v	boolean	no	False	Print verbose output.
--json	boolean	no	False	Output result as JSON.
--auto-add-deps	boolean	no	False	Automatically install missing kernel dependencies (e.g., IJulia for Julia environments).

calkit notebooks|nb execute

Execute notebook and place a copy in the relevant directory.

This can be useful to use as a preprocessing DVC stage to use a clean notebook as a dependency for a stage that caches and executed notebook.

Usage:

calkit notebooks|nb execute [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes

Options:

Option	Type	Required	Default	Description
--environment, -e	str	no		Name or path to the spec of the environment in which to run the notebook.
--to	str	no	notebook	Output format ('html' or 'notebook').
--no-check	boolean	no	False	Do not check environment before executing.
--param, -p	str	no		Parameter to pass to the notebook in key=value format.
--params-json, -j	str	no		JSON string to parse as parameters to pass to the notebook.
--params-base64, -b	str	no		Base64-encoded JSON string to parse as parameters to pass to the notebook.
--language, -l	str	no		Notebook language; if 'matlab', MATLAB kernel must be available in environment.
--no-replace	boolean	no	False	Do not replace notebook outputs from executed version.
--verbose, -v	boolean	no	False	Print verbose output.

calkit notebooks|nb export-marimo-wasm

Export a marimo notebook to a WebAssembly app.

Usage:

calkit notebooks|nb export-marimo-wasm [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Notebook path.

Options:

Option	Type	Required	Default	Description
-o, --output	str	yes		Output path for the app.
--environment, -e	str	no		Name or path to the spec of the environment in which to export the notebook; must include marimo.
--mode	str	no	run	Whether the app is read-only ('run') or editable.
--show-code	boolean	no	False	Show notebook code in the app.
--layout	str	no		Path to the layout file named in the notebook's marimo.App(layout_file=...) call.
--include	str	no		Path to publish with the app, copied beneath 'public' at its project-relative path. May be a glob, and may be repeated.
--no-validate	boolean	no	False	Skip executing the notebook to check it works before exporting.
--no-check	boolean	no	False	Do not check environment before exporting.
--verbose, -v	boolean	no	False	Print verbose output.

calkit list|ls

List Calkit objects.

Command	Description
notebooks\|nb	List notebooks in the project.
figures\|figs	List figures in the project.
datasets	List datasets in the project.
results	List results in the project.
presentations\|pres	List presentations in the project.
tables\|tbls	List tables in the project.
questions\|q	List the project's questions (1-indexed).
comments	List review comment threads in LaTeX and Markdown documents.
publications\|pubs	List publications in the project.
misc	List misc artifacts in the project, i.e., attributed paths that aren't one of the typed kinds.
references\|refs	List reference collections in the project.
environments\|envs	List environments in the project.
requirements\|reqs	List what a machine needs to run the project.
templates	List all available Calkit templates, grouped by kind.
installers	List apps with a registered native installer.
procedures	List procedures in the current project.
releases	List releases.
stages	List pipeline stages, including subprojects'.
subprojects	List subprojects, including nested ones, by path.
latex-diffs	List the LaTeX diffs the pipeline keeps and whether each is current.
remotes	List Git and DVC remotes.
imports	List everything in the project that was imported from elsewhere.

calkit list|ls notebooks|nb

List notebooks in the project.

Usage:

calkit list|ls notebooks|nb [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls figures|figs

List figures in the project.

Usage:

calkit list|ls figures|figs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--declared-only	boolean	no	False	Only list figures declared in calkit.yaml; skip auto-detection.

calkit list|ls datasets

List datasets in the project.

Usage:

calkit list|ls datasets [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--declared-only	boolean	no	False	Only list datasets declared in calkit.yaml; skip auto-detection.

calkit list|ls results

List results in the project.

Shown with the stage that writes each one, which is what 'calkit run' would use to bring it up to date.

Usage:

calkit list|ls results [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--declared-only	boolean	no	False	Only list results declared in calkit.yaml; skip auto-detection.
--status, -s	boolean	no	False	Also say whether each result's stage is up to date.

calkit list|ls presentations|pres

List presentations in the project.

Usage:

calkit list|ls presentations|pres [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--declared-only	boolean	no	False	Only list presentations declared in calkit.yaml; skip auto-detection.

calkit list|ls tables|tbls

List tables in the project.

Tabular files are detected wherever they're kept, so a table that is also a dataset or a result is listed here too. Each is shown with the stage that writes it, if any, which is the one 'calkit run' would use to bring it up to date.

Usage:

calkit list|ls tables|tbls [OPTIONS]

Options:

Option	Type	Required	Default	Description
--columns	boolean	no	False	Also read each table's column names from its header.
--status, -s	boolean	no	False	Also say whether each table's stage is up to date.
--json	boolean	no	False	Output result as JSON.
--declared-only	boolean	no	False	Only list tables declared in calkit.yaml; skip auto-detection.

calkit list|ls questions|q

List the project's questions (1-indexed).

Each has a row of letters: H if it has a hypothesis, A if it's answered, then V if it's verified and V if it's validated, colored as in the hub, with a dash for each it doesn't have yet. Evidence isn't checked against the pipeline here; 'calkit check questions' does that. Subprojects' questions are listed too, numbered within each. Use 'calkit show question' to see one in full.

Usage:

calkit list|ls questions|q [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls comments

List review comment threads in LaTeX and Markdown documents.

Usage:

calkit list|ls comments [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no		Document to list threads from, including files it inputs. Defaults to every document the pipeline builds into a PDF.

Options:

Option	Type	Required	Default	Description
--unresolved, -u	boolean	no	False	Only list open threads.
--json	boolean	no	False	Output result as JSON.

calkit list|ls publications|pubs

List publications in the project.

Usage:

calkit list|ls publications|pubs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls misc

List misc artifacts in the project, i.e., attributed paths that aren't one of the typed kinds.

Usage:

calkit list|ls misc [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls references|refs

List reference collections in the project.

Usage:

calkit list|ls references|refs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls environments|envs

List environments in the project.

Usage:

calkit list|ls environments|envs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls requirements|reqs

List what a machine needs to run the project.

That's the project's requirements, then those of each environment and stage, each with where it was declared. Nothing is checked; use 'calkit check reqs' for that.

Usage:

calkit list|ls requirements|reqs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls templates

List all available Calkit templates, grouped by kind.

A template is named by its kind and name, except a project template, which names a project on a hub and so is owner/project.

Usage:

calkit list|ls templates [OPTIONS]

Options:

Option	Type	Required	Default	Description
--kind, -k	str	no		Only show templates of one kind.
--json	boolean	no	False	Output result as JSON.

calkit list|ls installers

List apps with a registered native installer.

These can be declared as kind: app dependencies in calkit.yaml and Calkit will offer to install them via calkit install <name> or automatically during calkit run on an interactive TTY.

Usage:

calkit list|ls installers [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls procedures

List procedures in the current project.

Usage:

calkit list|ls procedures [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls releases

List releases.

Usage:

calkit list|ls releases [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls stages

List pipeline stages, including subprojects'.

Usage:

calkit list|ls stages [OPTIONS]

Options:

Option	Type	Required	Default	Description
--kind, -k	str	no		Filter stages by kind.
--stale	boolean	no	False	Show only stale stages.
--json	boolean	no	False	Output result as JSON.

calkit list|ls subprojects

List subprojects, including nested ones, by path.

Usage:

calkit list|ls subprojects [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls latex-diffs

List the LaTeX diffs the pipeline keeps and whether each is current.

Usage:

calkit list|ls latex-diffs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls remotes

List Git and DVC remotes.

Usage:

calkit list|ls remotes [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit list|ls imports

List everything in the project that was imported from elsewhere.

Walks every artifact kind, so an import shows up here whichever list it was recorded in. Entries are annotated with the kind they came from and a one-line description of the source, since where a file came from is the question being asked and it's spelled differently for a Git repo, a project, a URL, and a DOI.

What each import resolved to -- the commit, the checksum, when it was fetched -- is read from '.calkit/imports.json' and shown under 'locked', so both halves of the record are in one listing.

Usage:

calkit list|ls imports [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit show

Show Calkit objects.

Command	Description
question\|q	Show a question in full as Markdown, with its evidence and sign-offs.
latex-diff	Open a LaTeX diff the pipeline keeps.
table\|tbl	Show a table, or part of one.
result\|res	Show a result's keys and values.

calkit show question|q

Show a question in full as Markdown, with its evidence and sign-offs.

Placeholders in the text, such as {improvement:.1f}, are filled from the question's value evidence, so numbers shown are read from the results files rather than retyped into calkit.yaml. The pipeline stages behind its evidence are shown too, upstream first.

Usage:

calkit show question|q [OPTIONS] QUESTION

Arguments:

Argument	Type	Required	Default	Description
question	str	yes		The question's 1-based position, as 'calkit list questions' numbers it, or its name; prefix a subproject's with its path, e.g., 'sub:1'.

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--raw	boolean	no	False	Show the text as written, with its {name} placeholders, instead of rendered from the evidence.

calkit show latex-diff

Open a LaTeX diff the pipeline keeps.

From VS Code's terminal it opens in the editor, otherwise in the system's PDF viewer.

Usage:

calkit show latex-diff [OPTIONS] [TARGET]

Arguments:

Argument	Type	Required	Default	Description
target	str	no		Which diff: its stage or PDF, the document or its PDF, the latex stage, or the revision it compares against. Can be omitted if the project keeps only one.

Options:

Option	Type	Required	Default	Description
--run	boolean	no	False	Build the diff first if it's stale or not built.

calkit show table|tbl

Show a table, or part of one.

With --status, says whether the stage that writes the table has been run since its inputs last changed. At a --git-ref that's reconstructed from the dvc.lock committed there, since there is nothing on disk at an old commit for DVC to hash, and what it couldn't check is reported rather than assumed current.

Usage:

calkit show table|tbl [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path to the table.

Options:

Option	Type	Required	Default	Description
--column, -c	str	no		Only show these columns, in this order. Can be a glob, e.g., *_mod, and can be given more than once.
--filter, -f	str	no		Only show rows matching COLUMN=VALUE, COLUMN~TEXT (contains, ignoring case), or COLUMN>NUMBER. Can be given more than once, and all must match.
--rows, -r	str	no		Only show these rows, 1-based, e.g., '1-20', '5,9', '40-'.
--head, -n	int range	no		Only show the first N rows.
--tail	int range	no		Only show the last N rows.
--git-ref	str	no		Show the table as of this Git branch, tag, or commit instead of the working tree.
--status, -s	boolean	no	False	Also say whether the table is up to date.
--vscode	boolean	no	False	Open the table in VS Code instead of printing it.
--engine	str	no		Dataframe engine for formats the standard library can't read, e.g., Parquet. Defaults to the configured one.

calkit show result|res

Show a result's keys and values.

Keys are shown dotted, the way a question's value evidence names them, so what's printed is what an answer can cite. With --status, says whether the stage that writes the result has been run since its inputs last changed.

Usage:

calkit show result|res [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path to the result.

Options:

Option	Type	Required	Default	Description
--key, -k	str	no		Only show these keys, dotted as a question's evidence writes them, e.g., steady_state.saved_pct. Can be given more than once.
--depth, -d	int	no		Stop flattening this many levels in and show the rest of each value as JSON.
--git-ref	str	no		Show the result as of this Git branch, tag, or commit instead of the working tree.
--status, -s	boolean	no	False	Also say whether the result is up to date.
--vscode	boolean	no	False	Open the result in VS Code instead of printing it.
--json	boolean	no	False	Output result as JSON.

calkit describe|desc

Describe things.

Command	Description
system	Describe the system.
environment\|env	Describe a single environment, including spec and lock file paths.
environments\|envs	Describe all environments, including spec and lock file paths.
subprojects	Describe subprojects, including nested ones.
schema	Print the JSON schema for calkit.yaml.

calkit describe|desc system

Describe the system.

Usage:

calkit describe|desc system [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.
--app	str	no		An app whose version to include, beyond the ones always reported. Repeat for more.

calkit describe|desc environment|env

Describe a single environment, including spec and lock file paths.

Usage:

calkit describe|desc environment|env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--json	boolean	no	False	Output result as JSON.

calkit describe|desc environments|envs

Describe all environments, including spec and lock file paths.

Usage:

calkit describe|desc environments|envs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit describe|desc subprojects

Describe subprojects, including nested ones.

Stages and environments are named as in the subproject itself; from here, they're addressed as ':'.

Usage:

calkit describe|desc subprojects [OPTIONS]

Options:

Option	Type	Required	Default	Description
--json	boolean	no	False	Output result as JSON.

calkit describe|desc schema

Print the JSON schema for calkit.yaml.

Editors can use this to validate and autocomplete the file. See https://docs.calkit.org/calkit-yaml for how to set that up.

Usage:

calkit describe|desc schema [OPTIONS]

Options:

Option	Type	Required	Default	Description
--output, -o	str	no		Path at which to write the schema instead of printing it.

calkit import

Import objects.

Command	Description
dataset	Import a dataset.
path	Import a file from elsewhere, recording where it came from.
environment	Import an environment from another project.
zenodo	Import files from a Zenodo record.

calkit import dataset

Import a dataset.

Currently only supports datasets kept in DVC, not Git.

Usage:

calkit import dataset [OPTIONS] SRC-PATH [DEST-PATH]

Arguments:

Argument	Type	Required	Default	Description
src_path	str	yes		Location of dataset, including project owner and name, e.g., someone/some-project/data/some-data.csv
dest_path	str	no		Output path at which to save.

Options:

Option	Type	Required	Default	Description
--filter-paths	str	no		Filter paths in target dataset if it's a folder.
--no-commit	boolean	no	False	Do not commit changes to repo.
--no-dvc-pull	boolean	no	False	Do not pull imported dataset with DVC.
--overwrite, -f	boolean	no	False	Force adding the dataset even if it already exists.
--http	boolean	no	False	Use the legacy HTTP URL for the imported project's DVC remote instead of ck://.

calkit import path

Import a file from elsewhere, recording where it came from.

For a script or config maintained outside this project, e.g., a site setup script shared between projects. The copy is committed here, so the project stays self-contained and the pipeline can depend on it; the entry records the source so it can be refreshed with 'calkit sync import' and so the file isn't one whose origin nobody knows.

Usage:

calkit import path [OPTIONS] SRC-PATH [DEST-PATH]

Arguments:

Argument	Type	Required	Default	Description
src_path	str	yes		Where to get the file: a URL, including a GitHub or GitLab link to a file, an SSH clone URL like git@github.com:owner/repo/path, a DOI, a Calkit project path like someone/some-project/scripts/setup.sh, or a path inside the repo named by --git-repo.
dest_path	str	no		Path at which to save it in this project. Defaults to the path within the source project for a Calkit project source, and to the file's name for a Git repo, a URL, or anything else that has no project-relative path.

Options:

Option	Type	Required	Default	Description
--kind	str	no	misc	What kind of artifact this is: 'dataset', 'figure', 'publication', or 'misc' (default), which is where a path that isn't one of the typed artifacts belongs.
--git-repo	str	no		Clone URL of a Git repo to take the file from, for a repo that isn't a Calkit project.
--git-ref	str	no		Branch, tag, or commit to follow, recorded so 'calkit sync import' knows where to look next time, and overriding one read out of the URL. Needed for a URL whose branch name contains a slash. Defaults to the repo's default branch.
--title	str	no		Title for the entry.
--description	str	no		Description for the entry.
--overwrite, -f	boolean	no	False	Replace an existing file or entry at this path.
--no-commit	boolean	no	False	Do not commit changes to repo.

calkit import environment

Import an environment from another project.

Usage:

calkit import environment [OPTIONS] SRC

Arguments:

Argument	Type	Required	Default	Description
src	str	yes		Environment location and name, e.g., someone/some-project:env-name. If not present, the Calkit API will be queried.

Options:

Option	Type	Required	Default	Description
--path	str	no		Output path at which to save.
--name, -n	str	no		Name to use in the destination project.
--overwrite, -f	boolean	no	False	Force adding the dataset even if it already exists.
--no-commit	boolean	no	False	Do not commit changes.

calkit import zenodo

Import files from a Zenodo record.

Usage:

calkit import zenodo [OPTIONS] SRC DEST-DIR

Arguments:

Argument	Type	Required	Default	Description
src	str	yes		Source URL or DOI.
dest_dir	str	yes		Destination folder. Will be created if it doesn't exist

Options:

Option	Type	Required	Default	Description
--kind, -k	str	no		What kind of artifact is being imported, e.g., a figure, dataset, publication.
--name-like	str	no		Filter for file names like this. Glob patterns accepted.
--name-not-like	str	no		Exclude names matching pattern.
--storage	str	no		Storage backend to use (Git or DVC). If not specified, will be chosen based on size.
--no-commit	boolean	no	False	Do not commit changes to project.

calkit office

Work with Microsoft Office.

Command	Description
excel-chart-to-image	Extract a chart from Excel and save to image.
word-to-pdf	Convert a Word document to PDF.

calkit office excel-chart-to-image

Extract a chart from Excel and save to image.

Usage:

calkit office excel-chart-to-image [OPTIONS] INPUT-FPATH OUTPUT-FPATH

Arguments:

Argument	Type	Required	Default	Description
input_fpath	str	yes		Input Excel file path.
output_fpath	str	yes		Output image file path.

Options:

Option	Type	Required	Default	Description
--sheet	int	no	1	Sheet in workbook.
--chart-index	int	no	0	Chart index.

calkit office word-to-pdf

Convert a Word document to PDF.

Usage:

calkit office word-to-pdf [OPTIONS] INPUT-FPATH

Arguments:

Argument	Type	Required	Default	Description
input_fpath	str	yes		Input Word document file path.

Options:

Option	Type	Required	Default	Description
-o, --output	str	no		Output file path. If not specified, will be the same as input with a .pdf extension.

calkit update

Update objects.

Command	Description
devcontainer	Update a project's devcontainer to match this version of Calkit's spec.
license	Update license with a reasonable default (MIT for code, CC-BY-4.0 for other files).
release	Update a release.
vscode-config	Update a project's VS Code config to match this version of Calkit's recommendations.
github-actions	Update a project's GitHub Actions to match this version of Calkit's recommendations.
notebook	Update notebook information.
agent-skills	Copy packaged Calkit agent skills to ~/.agents/skills.
uv-env	Update a uv environment.
pixi-env	Update a pixi environment.
julia-env	Update a Julia environment.
conda-env	Update a conda environment spec file.
docker-env	Update a docker environment.
latex-image	Point LaTeX environments at Calkit's pinned LaTeX image.
slurm-env	Update a SLURM environment.
env	Update an environment.
environment	Update an environment.
stage	Update a pipeline stage in calkit.yaml.
figure	Update a figure entry in calkit.yaml.
question	Update a question in calkit.yaml, or verify or validate it.
path-storage	Move paths between Git and DVC storage without rerunning anything.
dataset	Update a dataset entry in calkit.yaml.
hub	Connect this project to a Calkit hub.
comment	Reply to, resolve, or reopen a review comment thread, printing its ID.

calkit update devcontainer

Update a project's devcontainer to match this version of Calkit's spec.

Usage:

calkit update devcontainer [OPTIONS]

Options:

Option	Type	Required	Default	Description
--wdir	str	no		Working directory. By default will run current working directory.
--no-commit	boolean	no	False	Do not create a Git commit for the updated devcontainer.

calkit update license

Update license with a reasonable default (MIT for code, CC-BY-4.0 for other files).

Usage:

calkit update license [OPTIONS]

Options:

Option	Type	Required	Default	Description
--copyright-holder, -c	str	yes		Copyright holder, e.g., your full name.
--no-commit	boolean	no	False	Do not create a Git commit for the updated license.

calkit update release

Update a release.

Usage:

calkit update release [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	no		Release name.
--latest	boolean	no	False	Update latest release.
--delete	boolean	no	False	Delete release.
--publish	boolean	no	False	Publish the release.
--reupload	boolean	no	False	Reupload files.
--no-github	boolean	no	False	Do not create a release on GitHub.
--no-push-tags	boolean	no	False	Do not push Git tags to remote repository.

calkit update vscode-config

Update a project's VS Code config to match this version of Calkit's recommendations.

Usage:

calkit update vscode-config [OPTIONS]

Options:

Option	Type	Required	Default	Description
--wdir	str	no		Working directory. By default will run current working directory.
--no-commit	boolean	no	False	Do not create a Git commit for the updated VS Code config.

calkit update github-actions

Update a project's GitHub Actions to match this version of Calkit's recommendations.

An existing workflow that runs the Calkit action is updated in place, pinning the action to this version of Calkit, so this is safe to rerun after upgrading.

Usage:

calkit update github-actions [OPTIONS]

Options:

Option	Type	Required	Default	Description
--wdir	str	no		Working directory. By default will run current working directory.
--no-commit	boolean	no	False	Do not create a Git commit for the updated GitHub Actions.

calkit update notebook

Update notebook information.

Updates the notebook's environment association in either the 'notebooks' section or the appropriate 'pipeline' stage, depending on whether the notebook has a corresponding pipeline stage.

Usage:

calkit update notebook [OPTIONS] NOTEBOOK-PATH

Arguments:

Argument	Type	Required	Default	Description
notebook_path	str	yes		Path to the notebook file (relative to workspace)

Options:

Option	Type	Required	Default	Description
--set-env	str	no		Environment name to associate with the notebook
--json	boolean	no	False	Output result as JSON.

calkit update agent-skills

Copy packaged Calkit agent skills to ~/.agents/skills.

Usage:

calkit update agent-skills [OPTIONS]

Options:

Option	Type	Required	Default	Description
--quiet, -q	boolean	no	False	Suppress non-essential output.

calkit update uv-env

Update a uv environment.

Usage:

calkit update uv-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--add	str	no		Add a package.
--remove, --rm	str	no		Remove a package.
--no-check	boolean	no	False	Skip checking (syncing) the environment after updating.

calkit update pixi-env

Update a pixi environment.

Usage:

calkit update pixi-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--add	str	no		Add a conda package.
--remove, --rm	str	no		Remove a conda package.
--add-pip	str	no		Add a PyPI package.
--remove-pip, --rm-pip	str	no		Remove a PyPI package.
--no-check	boolean	no	False	Skip checking (syncing) the environment after updating.

calkit update julia-env

Update a Julia environment.

Usage:

calkit update julia-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--add	str	no		Add a package.
--remove, --rm	str	no		Remove a package.
--no-check	boolean	no	False	Skip checking (syncing) the environment after updating.

calkit update conda-env

Update a conda environment spec file.

Usage:

calkit update conda-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--add	str	no		Add a conda package.
--remove, --rm	str	no		Remove a conda package.
--add-pip	str	no		Add a pip package.
--remove-pip, --rm-pip	str	no		Remove a pip package.
--no-check	boolean	no	False	Skip checking (syncing) the environment after updating.

calkit update docker-env

Update a docker environment.

Usage:

calkit update docker-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--image	str	no		Docker image name/tag.
--registry	str	no		Registry prefix to push images to and pull them from, or 'ghcr.io' for the project's own namespace in the GitHub Container Registry, or 'none' to keep images local.
--lock	boolean	no	False	Rebuild or repull the image and write fresh lock files for every architecture.

calkit update latex-image

Point LaTeX environments at Calkit's pinned LaTeX image.

Updates Docker environments that use Calkit or TeX Live's LaTeX images, including ones a switch defines in place, then relocks them.

Usage:

calkit update latex-image

calkit update slurm-env

Update a SLURM environment.

Usage:

calkit update slurm-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name.
--host	str	no		SLURM host.
--add-default-option	str	no		Add a default sbatch option.
--rm-default-option	str	no		Remove a default sbatch option.
--set-default-options	str	no		Replace default options list.
--add-default-setup	str	no		Add a default setup command.
--rm-default-setup	str	no		Remove a default setup command.
--set-default-setup	str	no		Replace default setup list.
--max-concurrent-jobs	int	no		Maximum number of this project's jobs allowed in the queue at once, or 0 to remove the limit.

calkit update env

Update an environment.

Currently supports adding packages to Julia and Nix (flake) envs, and re-locking a system environment to this machine.

Usage:

calkit update env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Name of the environment to update
--add, --add-package	str	no		Package to add to the environment. Repeat the flag for multiple packages.
--lock, --relock	boolean	no	False	Record this machine's properties in a system environment's lock file, replacing the machine it is locked to. Invalidates every stage that depends on it.

calkit update environment

Update an environment.

Currently supports adding packages to Julia and Nix (flake) envs, and re-locking a system environment to this machine.

Usage:

calkit update environment [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Name of the environment to update
--add, --add-package	str	no		Package to add to the environment. Repeat the flag for multiple packages.
--lock, --relock	boolean	no	False	Record this machine's properties in a system environment's lock file, replacing the machine it is locked to. Invalidates every stage that depends on it.

calkit update stage

Update a pipeline stage in calkit.yaml.

Usage:

calkit update stage [OPTIONS] NAME

Arguments:

Argument	Type	Required	Default	Description
name	str	yes		Stage name.

Options:

Option	Type	Required	Default	Description
--environment, -e	str	no		Set environment.
--add-input	str	no		Add an input path.
--rm-input	str	no		Remove an input path.
--set-inputs	str	no		Replace the inputs list.
--set-outputs	str	no		Replace DVC outputs list (paths only, storage=dvc).
--set-outputs-git	str	no		Replace Git-tracked outputs list.
--add-output	str	no		Add a DVC-tracked output path.
--rm-output	str	no		Remove an output path.

calkit update figure

Update a figure entry in calkit.yaml.

Usage:

calkit update figure [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path to the figure file.

Options:

Option	Type	Required	Default	Description
--imported-from	str	no		Where this came from, as a URL, a DOI, a Git clone URL, a Calkit project path, or, failing all of those, a description in words. Which one it is is worked out from how it's written.
--imported-from-url	str	no		URL the figure was imported from.
--stage	str	no		Name of the pipeline stage that produces this figure.

calkit update question

Update a question in calkit.yaml, or verify or validate it.

A sign-off is recorded with your Git name and email and the time, replaces any earlier one of yours of the same kind, and applies to the question as updated by this command.

Usage:

calkit update question [OPTIONS] QUESTION

Arguments:

Argument	Type	Required	Default	Description
question	str	yes		The question's 1-based position, as 'calkit list questions' numbers it, or its name.

Options:

Option	Type	Required	Default	Description
--hypothesis	str	no		New hypothesis.
--approach	str	no		One sentence on how the question is answered.
--answer	str	no		New answer. One that picks its wording from the evidence is written in calkit.yaml.
--notes	str	no		New notes on the question.
--verify	str	no		Sign off that the pipeline stages behind the evidence implement the approach correctly, with what you checked, e.g., 'fit.py fits both models as stated.'
--validate	str	no		Sign off that the approach suits the question and the evidence justifies the answer, with what you checked, e.g., 'The linear fit's residuals curve.'
--with-ai	str	no		A generative AI tool used in verifying or validating, e.g., 'Claude Opus 5'. Can be given more than once.

calkit update path-storage

Move paths between Git and DVC storage without rerunning anything.

A pipeline output's storage is changed where the pipeline declares it, e.g., an output's 'storage' or a LaTeX stage's 'pdf_storage', and a file added on its own is added again with the other system. Either way it's untracked from where it was, so it isn't left in both. The tracking changes are staged, and calkit.yaml and dvc.yaml are left to commit.

Usage:

calkit update path-storage [OPTIONS] PATHS...

Arguments:

Argument	Type	Required	Default	Description
paths	str	yes		Files or directories to move, from the project.

Options:

Option	Type	Required	Default	Description
--to, -t	str	yes		Where to store them: git or dvc.

calkit update dataset

Update a dataset entry in calkit.yaml.

Usage:

calkit update dataset [OPTIONS] PATH

Arguments:

Argument	Type	Required	Default	Description
path	str	yes		Path to the dataset file.

Options:

Option	Type	Required	Default	Description
--imported-from	str	no		Where this came from, as a URL, a DOI, a Git clone URL, a Calkit project path, or, failing all of those, a description in words. Which one it is is worked out from how it's written.
--imported-from-url	str	no		URL the dataset was imported from.
--imported-from-doi	str	no		DOI the dataset was imported from, e.g. 10.5281/zenodo.1.
--imported-from-git-url	str	no		Clone URL of the Git repo the dataset was imported from.
--imported-from-git-ref	str	no		Branch, tag, or commit to follow, e.g. 'main'. The commit it resolves to is recorded in .calkit/imports.json by 'calkit sync import', not here.
--imported-from-git-path	str	no		Path within that repo, if it isn't the whole thing.
--imported-from-date	datetime	no		Date it was downloaded, as YYYY-MM-DD.
--stage	str	no		Name of the pipeline stage that produces this dataset.

calkit update hub

Connect this project to a Calkit hub.

Creates the project on the hub if it isn't there, then points DVC at the hub's storage so data and outputs have somewhere to go. This is what 'calkit new project --hub' does at creation time, for a project that was created without it.

A project that already has a Git remote keeps it: the hub adopts that repository rather than creating a second one for the same work. One with no remote is offered a new repository, since otherwise there is nowhere to push code.

Usage:

calkit update hub [OPTIONS] [HUB]

Arguments:

Argument	Type	Required	Default	Description
hub	str	no		Hub to connect this project to, e.g., 'calkit.io'. Defaults to the one already set for the project, else the 'default_hub' config value, else calkit.io.

Options:

Option	Type	Required	Default	Description
--public	boolean	no	False	Create the project as public.
--create-repo	boolean	no	False	Let the hub create a Git repository without asking, for a project that has no remote. Asked about interactively when not given.
--no-commit	boolean	no	False	Do not commit the changes.

calkit update comment

Reply to, resolve, or reopen a review comment thread, printing its ID.

Usage:

calkit update comment [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no		File the thread is in, if not found by --id.

Options:

Option	Type	Required	Default	Description
--id	str	no		ID of the thread, which finds it in any of the project's documents.
--line, -l	int	no		Number of any line in the thread.
--reply, -r	str	no		Reply to the thread.
--resolve	boolean	no	False	Mark the thread resolved.
--reopen	boolean	no	False	Mark the thread open again.
--author	str	no		Defaults to Git's user.name.
--email	str	no		Defaults to Git's user.email.

calkit check

Check things.

Command	Description
repro	Check the reproducibility of a project.
environment	Check that an environment is up-to-date.
julia-env	Check a Julia environment and instantiate only when project, manifest, and package cache state have changed.
environments	Check that the project's environments are up to date.
envs	Check that all environments are up-to-date.
renv	Check an renv R environment, initializing if needed.
docker-env	Check that Docker environment is up-to-date.
conda-env	Check a conda environment and rebuild if necessary.
venv	Check a Python virtual environment (uv or virtualenv).
matlab-env	Check a MATLAB environment matches its spec and export a JSON lock file.
reqs\|requirements	Check that a project's system-level requirements are met.
stage-runs	Check each stage in dvc.lock matches the recorded run that made it.
env-vars	Check that the project's required environmental variables exist.
pipeline	Check that the project pipeline is defined correctly.
storage	Check that paths are tracked where they're declared to be stored.
call	Check that a command succeeds and run an alternate if not.
questions	Check that answered questions are backed by current evidence.

calkit check repro

Check the reproducibility of a project.

Reports one line per check. Where a line counts something, ask for that category to see what it counted, e.g., 'calkit check repro -c retyped' for values in a manuscript the pipeline already computes.

Exits with an error when the project types out a value its own pipeline computes, which is a defect rather than a matter of taste. Everything else here is advice and does not affect the exit code.

Usage:

calkit check repro [OPTIONS]

Options:

Option	Type	Required	Default	Description
--wdir	str	no	.	Project working directory.
--category, -c	str	no		Show the findings behind one summary line instead of the summary. Can be specified multiple times.
--json	boolean	no	False	Output result as JSON.

calkit check environment

Check that an environment is up-to-date.

An environment is also rebuilt when one of its 'inputs' changes.

Usage:

calkit check environment [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Name of the environment to check.
--verbose	boolean	no	False	Print verbose output.
--force, -f	boolean	no	False	Rebuild the environment from scratch, e.g., after something it was built from changed outside the project.

calkit check julia-env

Check a Julia environment and instantiate only when project, manifest, and package cache state have changed.

Usage:

calkit check julia-env [OPTIONS] [ENV-PATH]

Arguments:

Argument	Type	Required	Default	Description
env_path	str	no	Project.toml	Path to Julia Project.toml file.

Options:

Option	Type	Required	Default	Description
--julia	str	no		Julia version to enforce (e.g., 1.11).
--verbose	boolean	no	False	Print verbose output.

calkit check environments

Check that the project's environments are up to date.

Subprojects' environments are checked too, as 'calkit run' does.

Usage:

calkit check environments [OPTIONS]

Options:

Option	Type	Required	Default	Description
--verbose	boolean	no	False	Print verbose output.

calkit check envs

Check that all environments are up-to-date.

Usage:

calkit check envs [OPTIONS]

Options:

Option	Type	Required	Default	Description
--verbose	boolean	no	False	Print verbose output.

calkit check renv

Check an renv R environment, initializing if needed.

Usage:

calkit check renv [OPTIONS] ENV-PATH

Arguments:

Argument	Type	Required	Default	Description
env_path	str	yes		Path to DESCRIPTION file or renv environment directory.

Options:

Option	Type	Required	Default	Description
--verbose	boolean	no	False	Print verbose output.

calkit check docker-env

Check that Docker environment is up-to-date.

Usage:

calkit check docker-env [OPTIONS] TAG

Arguments:

Argument	Type	Required	Default	Description
tag	str	yes		Image tag.

Options:

Option	Type	Required	Default	Description
-i, --input	str	no		Path to input Dockerfile, if applicable.
--output, -o	str	no		Path to which existing environment should be exported. If not specified, will have the same filename with '-lock' appended to it, keeping the same extension.
--input	str	no		Alternative lock file input paths to read.
--input-delete	str	no		Alternative lock input file paths to read and remove (i.e., legacy paths).
--platform	str	no		Platform to pull and run the image as, e.g., 'linux/amd64'. Also used when building, unless --platform-build says otherwise.
--user	str	no		Which user to run the container as.
--wdir	str	no		Working directory inside the container.
--dep, -d	str	no		Declare an explicit dependency for this Docker image.
--env-var, -e	str	no		Declare an explicit environment variable for the container.
--port, -p	str	no		Declare an explicit port for the container.
--gpus, -g	str	no		Declare an explicit GPU requirement for the container.
--arg, -a	str	no		Declare an explicit run argument for the container.
--platform-build	str	no		Platform to build the image for, as opposed to --platform, which is the one it's pulled and run as. Repeat for a multi-platform image, which requires a registry.
--registry	str	no		Registry prefix to push built images to and pull them from, e.g., 'ghcr.io/someone/some-project', or 'none' to disable.
--lock-arch	str	no		Architecture to write an additional lock file for, alongside this machine's, e.g., 'amd64'.
--quiet, -q	boolean	no	False	Be quiet.
--rebuild	boolean	no	False	Build the image from scratch, pulling its base image, rather than reusing a cached or locked one.

calkit check conda-env

Check a conda environment and rebuild if necessary.

Usage:

calkit check conda-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--file, -f	str	no	environment.yml	Path to conda environment YAML file.
--output, -o	str	no		Path to which existing environment should be exported. If not specified, will have the same filename with '-lock' appended to it, keeping the same extension.
--input	str	no		Alternative lock file input paths.
--input-delete	str	no		Alternative lock file input paths to delete after use.
--relaxed	boolean	no	False	Treat conda and pip dependencies as equivalent.
--quiet, -q	boolean	no	False	Be quiet.

calkit check venv

Check a Python virtual environment (uv or virtualenv).

Usage:

calkit check venv [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no	requirements.txt	Path to requirements file.

Options:

Option	Type	Required	Default	Description
--prefix	str	no	.venv	Prefix.
--output, -o	str	no		Path to which existing environment should be exported. If not specified, will have the same filename with '-lock' appended to it, keeping the same extension.
--input	str	no		Alternative lock file input paths.
--input-delete	str	no		Alternative lock file input paths to delete after use.
--wdir	str	no		Working directory. Defaults to current working directory.
--uv	boolean	no	True	Use uv.
--python	str	no		Python version to specify if using uv.
--quiet	boolean	no	False	Do not print any output
--verbose	boolean	no	False	Print verbose output.

calkit check matlab-env

Check a MATLAB environment matches its spec and export a JSON lock file.

Usage:

calkit check matlab-env [OPTIONS]

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Environment name in calkit.yaml.
--output, -o	str	yes
--rebuild	boolean	no	False	Rebuild the image from scratch.

calkit check reqs|requirements

Check that a project's system-level requirements are met.

Subprojects' requirements are checked too, since the host has to meet them for the project's pipeline to run.

Usage:

calkit check reqs|requirements [OPTIONS]

Options:

Option	Type	Required	Default	Description
--verbose, -v	boolean	no	False	Print verbose output
--no-cache	boolean	no	False	Re-probe every setup requirement, ignoring (and clearing) the cache at .calkit/local/dep-checks.sqlite.

calkit check stage-runs

Check each stage in dvc.lock matches the recorded run that made it.

A stage's entry in .calkit/stage-runs.json records a checksum of its dvc.lock entry after it ran, so one that disagrees got its dvc.lock entry some other way, e.g., 'dvc commit' after an output was edited, an edit or merge of dvc.lock, or running it outside Calkit. This catches mistakes and shortcuts, not forgery, since a matching entry can be written by anyone.

Usage:

calkit check stage-runs

calkit check env-vars

Check that the project's required environmental variables exist.

Subprojects' are included, since they are read from the same environment.

Usage:

calkit check env-vars [OPTIONS]

Options:

Option	Type	Required	Default	Description
--verbose, -v	boolean	no	False	Print verbose output

calkit check pipeline

Check that the project pipeline is defined correctly.

Subprojects' pipelines are checked too, since those are stages the project runs.

Usage:

calkit check pipeline [OPTIONS]

Options:

Option	Type	Required	Default	Description
--compile, -c	boolean	no	False	Compile the pipeline to DVC stages and merge into dvc.yaml.

calkit check storage

Check that paths are tracked where they're declared to be stored.

That is, nothing is tracked by both Git and DVC, no pipeline output stored in Git is ignored by it, and nothing in Git is too large for it. With --fix, the pipeline's declarations, or a file's .dvc file, decide where each path belongs, and the changes are staged.

Usage:

calkit check storage [OPTIONS]

Options:

Option	Type	Required	Default	Description
--fix	boolean	no	False	Move each path to where it's declared to be stored.
--json	boolean	no	False	Output the problems as JSON.

calkit check call

Check that a command succeeds and run an alternate if not.

Usage:

calkit check call [OPTIONS] CMD

Arguments:

Argument	Type	Required	Default	Description
cmd	str	yes		Command to check.

Options:

Option	Type	Required	Default	Description
--if-error	str	yes		Command to run if there is an error.

calkit check questions

Check that answered questions are backed by current evidence.

Reports, worst first: evidence that isn't there (never run, never pushed, or pinned to a Git ref that doesn't exist); broken references (a key that doesn't resolve, a placeholder that names no evidence, a label missing from the LaTeX); evidence the pipeline would rebuild; and evidence from a frozen stage, or downstream of one, that no longer matches dvc.lock, which won't be rerun, unless the citation pins a git_ref. Subprojects' questions are checked too.

Evidence pinned with a git_ref is checked at that ref rather than in the working tree. Exits with an error if any answered question is missing evidence, broken, or out of date with the pipeline.

Usage:

calkit check questions [OPTIONS]

Options:

Option	Type	Required	Default	Description
--wdir	str	no	.	Project working directory.
--verbose, -v	boolean	no	False	List every answered question and its evidence, not only the ones needing attention.
--json	boolean	no	False	Output the report as JSON.
--no-pipeline	boolean	no	False	Skip asking DVC which stages are out of date, which is the slowest part of the check.

calkit fix

Fix things.

Command	Description
merge-conflicts	Resolve merge conflicts in dvc.lock and stage run records.
storage	Move paths to where they're declared to be stored (Git or DVC).

calkit fix merge-conflicts

Resolve merge conflicts in dvc.lock and stage run records.

Each stage is merged whole. A stage changed on one side takes that side, and one changed on both needs a choice, which also decides its run record and Git-tracked outputs. Stages are named as in 'calkit check stage-runs', e.g., 'sub/dvc.yaml:stage' for a subproject's.

Usage:

calkit fix merge-conflicts [OPTIONS]

Options:

Option	Type	Required	Default	Description
--ours, -o	str	no		Keep our side of this stage (repeatable).
--theirs, -t	str	no		Keep their side of this stage (repeatable).
--rerun, -r	str	no		Keep neither side of this stage, so it reruns (repeatable).
--prefer	str	no		Choice for every other stage changed on both sides (ours, theirs, or rerun).

calkit fix storage

Move paths to where they're declared to be stored (Git or DVC).

Same as 'calkit check storage --fix'.

Usage:

calkit fix storage

calkit latex|tex

Work with LaTeX.

Command	Description
from-json	Convert a JSON file to LaTeX.
from-questions	Write the project's questions and answers as a LaTeX command.
from-markdown	Build a Markdown file into a PDF with pandoc and LaTeX.
map-components	Map in components a LaTeX document includes with \ck* commands.
build	Build a PDF of a LaTeX document with latexmk.
diff	Build a PDF showing what changed in a LaTeX document.
to-docx	Export a Word copy of a LaTeX document for review.
merge-docx	Merge a reviewed Word document back into the LaTeX source.

calkit latex|tex from-json

Convert a JSON file to LaTeX.

This is useful for referencing calculated values in LaTeX documents.

Usage:

calkit latex|tex from-json [OPTIONS] INPUT-FPATHS...

Arguments:

Argument	Type	Required	Default	Description
input_fpaths	str	yes		Input JSON file path(s).

Options:

Option	Type	Required	Default	Description
--output, -o	str	yes		Output LaTeX file path(s).
--command	str	no		Command name to use in LaTeX output.
--key	str	no		Key to expose, dotted to reach into nested output, e.g., 'cases.a.cp'. Repeatable. Without any, every top-level key is exposed.
--format-json	str	no		Additional JSON input to use for formatting. Can be used to add extra keys with simple expressions, etc.

calkit latex|tex from-questions

Write the project's questions and answers as a LaTeX command.

Each question's text, hypothesis, answer, and notes are rendered from their evidence and exposed as, e.g., \questions[staging.answer], keyed by the question's name or its 1-based position.

Usage:

calkit latex|tex from-questions [OPTIONS]

Options:

Option	Type	Required	Default	Description
--output, -o	str	yes		Output LaTeX file path(s).
--command	str	no	questions	Command name to use in LaTeX output.

calkit latex|tex from-markdown

Build a Markdown file into a PDF with pandoc and LaTeX.

Value markers are filled from their results files, which keeps the Markdown itself current too, and each value links to the question on the project's hub whose evidence cites it. The template gets the Calkit version and the project's URL as the calkit-version, project-url, and project variables.

Usage:

calkit latex|tex from-markdown [OPTIONS] MD-PATH

Arguments:

Argument	Type	Required	Default	Description
md_path	str	yes		The Markdown file to build.

Options:

Option	Type	Required	Default	Description
--output, -o	str	yes		Where to write the PDF, or the LaTeX with a .tex extension; can be given more than once.
--environment, -e	str	no		Environment to run pandoc and LaTeX in, e.g., one using Calkit's LaTeX image, which includes both.
--template	str	no		Pandoc template.
--filter	str	no		Pandoc Lua filter; can be given more than once.
--pandoc-arg	str	no		Another argument for pandoc; can be given more than once.
--no-check	boolean	no	False	Don't check the environment first.
--verbose, -v	boolean	no	False	Print commands.

calkit latex|tex map-components

Map in components a LaTeX document includes with \ck* commands.

Usage:

calkit latex|tex map-components TEX-FILE

Arguments:

Argument	Type	Required	Default	Description
tex_file	str	yes		The .tex file whose components to map.

calkit latex|tex build

Build a PDF of a LaTeX document with latexmk.

If a Calkit environment is not specified, latexmk will be run in the system environment if available. If not available, a TeX Live Docker container will be used.

Usage:

calkit latex|tex build [OPTIONS] TEX-FILE

Arguments:

Argument	Type	Required	Default	Description
tex_file	str	yes		The .tex file to compile.

Options:

Option	Type	Required	Default	Description
--env, -e	str	no		Environment in which to run latexmk, if applicable.
--no-check	boolean	no	False	Don't check the environment is valid before running latexmk.
--latexmk-rc, -r	str	no		Path to a latexmkrc file to use for compilation.
--output-dir	str	no		Directory for the compiled PDF, relative to the current directory. Passed to latexmk as -outdir.
--aux-dir	str	no		Directory for auxiliary files, relative to the current directory. Passed to latexmk as -auxdir.
--latexmk-arg	str	no		Extra argument to pass through to latexmk. Repeat the option to pass more than one.
--no-synctex	boolean	no	False	Don't generate synctex file for source-to-pdf mapping.
--force, -f	boolean	no	False	Force latexmk to recompile all files, even if they are up to date.
--verbose, -v	boolean	no	False	Print verbose output.

calkit latex|tex diff

Build a PDF showing what changed in a LaTeX document.

Two revisions that turn out to be the same is a result rather than an error: the marked-up document comes out unmarked, which is what "this branch hasn't changed the paper" looks like. A pipeline shouldn't fail depending on which branch it runs from.

Marks up one revision of a document against another with latexdiff, so additions and deletions are visible where they happen rather than as a list of files that changed. A .dvc pointer in a pull request says a paper was rebuilt; this says what it now reads.

With the default --to, the newer side is the working tree, so the marked-up document is built with the current figures and bibliography and what's marked is what changed in the text.

A revision's DVC-tracked inputs, e.g., figures and tables a pipeline generates, are fetched as they were at that revision, so each side of the comparison shows its own.

Usage:

calkit latex|tex diff [OPTIONS] TEX-FILE

Arguments:

Argument	Type	Required	Default	Description
tex_file	str	yes		The .tex file to compare.

Options:

Option	Type	Required	Default	Description
--from	str	no		Older revision, whose removed text is struck through. Defaults to the merge base with the default branch.
--to	str	no		Newer revision, whose additions are marked. Defaults to the working tree.
--env, -e	str	no		Environment in which to run latexdiff and latexmk.
--output, -o	str	no		Where to write the diff PDF. Defaults to a path under .calkit/latex-diffs, keeping it with the project's other derived files.
--output-dir	str	no		Directory to write the diff into, keeping the document's own path inside it. Lets a pipeline name the location after the revisions as written while passing resolved commits to --from and --to.
--latexmk-rc, -r	str	no		Path to a latexmkrc file to build the marked-up document with.
--latexmk-arg	str	no		Extra argument to pass through to latexmk. Repeat the option to pass more than one.
--latexdiff-arg	str	no		Extra argument to pass through to latexdiff, e.g., '--type=CFONT'. Changed figures are shown old and new by default; pass '--graphics-markup=new-only' to show only the new. Repeat the option to pass more than one.
--input	str	no		File or directory the document reads. Anything in it tracked with DVC is fetched as it was at each revision. Defaults to the inputs detected in the document. Repeat the option to pass more than one.
--force, -f	boolean	no	False	Rebuild even if nothing the diff depends on has changed since it was last built.
--keep-tex	boolean	no	False	Keep the old, new, and diff .tex files beside the diff PDF for inspection, e.g., .calkit/latex-diffs/v1/paper/main-old.tex.
--filter-script	str	no		Python script to pipe the marked-up document through before it's built, e.g., to drop changes that don't change the rendered text. It reads the document on stdin and writes the result to stdout.
--filter-env	str	no		Environment to run the filter script in. Defaults to Calkit's own Python.
--filter-arg	str	no		Argument to pass to the filter script. Repeat the option to pass more than one.
--no-check	boolean	no	False	Don't check the environment is valid before running.
--verbose, -v	boolean	no	False	Print verbose output.

calkit latex|tex to-docx

Export a Word copy of a LaTeX document for review.

Uses Word's own PDF import where Word is installed, so the copy looks like the PDF, else TeX4ht and LibreOffice. Then records inside the file which source line each paragraph came from and the text as sent, so merge-docx can bring edits and comments back.

Usage:

calkit latex|tex to-docx [OPTIONS] PDF-PATH

Arguments:

Argument	Type	Required	Default	Description
pdf_path	str	yes		Compiled PDF to export.

Options:

Option	Type	Required	Default	Description
--source	str	no		Main .tex file. Defaults to the pipeline stage's target, else the .tex next to the PDF.
--output, -o	str	no		Where to write the .docx. Defaults to -for-review.docx.
--comment-only	boolean	no	False	Lock the document to comments.
--force, -f	boolean	no	False	Overwrite an existing export.
--engine	str	no		What makes the Word copy: 'word', which imports the compiled PDF so the copy looks like it, or 'libreoffice', which converts the source with TeX4ht's make4ht and then LibreOffice. Defaults to Word where it's installed.
--log, -l	boolean	no	False	Also keep the export record in the project, under .calkit/latex/docx-exports, rather than only on this machine.

calkit latex|tex merge-docx

Merge a reviewed Word document back into the LaTeX source.

Accepted changes are applied. Tracked changes not yet accepted or rejected, and edits that no longer fit the source, are left alone with a warning: deal with them in Word and merge again. Comments become comment blocks above the paragraph; threads resolved in Word are marked resolved.

Usage:

calkit latex|tex merge-docx [OPTIONS] DOCX-PATH

Arguments:

Argument	Type	Required	Default	Description
docx_path	str	yes		Reviewed .docx to merge.

Options:

Option	Type	Required	Default	Description
--no-comments	boolean	no	False	Don't write comments to the .tex.
--log, -l	boolean	no	False	Also keep the merge record in the project, under .calkit/latex/docx-merges, rather than only on this machine.

calkit overleaf|ol

Interact with Overleaf.

Command	Description
login	Sign in with a browser session to sync without Overleaf Premium.
import	Import a publication from an Overleaf project.
link	Link a folder in the project to an Overleaf project, pushing its files there.
sync	Sync folders with Overleaf.
status\|st	Check the status of folders synced with Overleaf in a project.
push	Get the project's latest figures and text onto Overleaf.
pull	Bring collaborators' Overleaf writing back into the project.

calkit overleaf|ol login

Sign in with a browser session to sync without Overleaf Premium.

Usage:

calkit overleaf|ol login [OPTIONS]

Options:

Option	Type	Required	Default	Description
--session	str	no		Value of the 'overleaf_session2' cookie from your browser.
--hub	boolean	no	False	Also save session to Calkit hub, so it can sync there.

calkit overleaf|ol import

Import a publication from an Overleaf project.

Usage:

calkit overleaf|ol import [OPTIONS] SRC-URL DEST-DIR

Arguments:

Argument	Type	Required	Default	Description
src_url	str	yes		Overleaf project URL, e.g., https://www.overleaf.com/project/6800005973cb2e35.
dest_dir	str	yes		Directory at which to save in the project, e.g., 'paper'.

Options:

Option	Type	Required	Default	Description
--title, -t	str	no		Title of the publication.
--target, -T	str	no		Target TeX file path inside Overleaf project.
--description, -d	str	no		Description of the publication.
--kind	str	no		What of the publication this is, e.g., 'journal-article'.
--push-path, -p	str	no		Paths to push to the Overleaf project, e.g., 'figures'. Note that these are relative to the publication working directory.
--no-commit	boolean	no	False	Do not commit changes to repo.
--overwrite, -f	boolean	no	False	Force adding the publication even if it already exists.
--push-only, -P	boolean	no	False	Push local files to Overleaf without pulling. Useful when initializing a new Overleaf project from local files.

calkit overleaf|ol link

Link a folder in the project to an Overleaf project, pushing its files there.

Like 'import --push-only', for a document that starts in the project.

Usage:

calkit overleaf|ol link [OPTIONS] FOLDER PROJECT-URL

Arguments:

Argument	Type	Required	Default	Description
folder	str	yes		Folder in the project, e.g., 'paper'.
project_url	str	yes		Overleaf project URL, e.g., https://www.overleaf.com/project/6800005973cb2e35.

Options:

Option	Type	Required	Default	Description
--title, -t	str	no		Title, if the publication isn't in calkit.yaml yet.
--target, -T	str	no		Target TeX file in the folder.
--push-path, -p	str	no		Paths in the folder to only push to Overleaf, e.g., 'figures'.
--no-commit	boolean	no	False	Do not commit changes to repo.

calkit overleaf|ol sync

Sync folders with Overleaf.

Local edits are committed first, and documents changed on either side are rebuilt and saved with the sync.

Usage:

calkit overleaf|ol sync [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to sync with Overleaf, e.g., 'paper/paper.pdf'. If not provided, all Overleaf publications will be synced.

Options:

Option	Type	Required	Default	Description
--no-commit	boolean	no	False	Do not create a commit in the project repo for this sync. Changes pulled from Overleaf are still applied, but are left staged so you can review or commit them yourself. Changes are always committed and pushed to Overleaf regardless.
--no-push	boolean	no	False	Do not push the changes to the main project remote. Changes will always be pushed to Overleaf.
--verbose	boolean	no	False	Enable verbose output.
--resolve, -r	boolean	no	False	Mark merge conflicts as resolved before committing.
--push-only, -P	boolean	no	False	Only push local files to Overleaf without pulling from Overleaf. Useful when initializing a new Overleaf project from local files.
--allow-stale	boolean	no	False	Sync even if the pipeline is out-of-date, which can send stale figures or results to Overleaf.
--any-branch	boolean	no	False	Sync even if the current branch is missing commits from the default branch.
--force, -f	boolean	no	False	Overwrite changes made on Overleaf to push-only paths, which the project is meant to be the source of truth for.
--no-build	boolean	no	False	Only sync source files, without rebuilding documents changed on Overleaf.
--upstream	boolean	no	False	When rebuilding, also run stages the build depends on.
--no-pull	boolean	no	False	Don't pull new commits from the project remote first, e.g., from a sync on the hub.

calkit overleaf|ol status|st

Check the status of folders synced with Overleaf in a project.

Usage:

calkit overleaf|ol status|st [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths synced with Overleaf, e.g., 'paper'. If not provided, all Overleaf syncs will be checked.

calkit overleaf|ol push

Get the project's latest figures and text onto Overleaf.

Pulls the latest data, ensures the pipeline is up-to-date, then pushes to Overleaf without pulling anything back, so collaborators see current results before they write against them.

Usage:

calkit overleaf|ol push [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to push to Overleaf, e.g., 'paper'. If not provided, all Overleaf publications will be pushed.

Options:

Option	Type	Required	Default	Description
--branch, -b	str	no		Switch to (or create) this branch before pushing.
--yes, -y	boolean	no	False	Answer yes to all prompts, e.g., to run non-interactively.
--no-pull	boolean	no	False	Do not pull from Git and DVC beforehand.
--allow-stale	boolean	no	False	Push even if the pipeline is out-of-date.
--any-branch	boolean	no	False	Push even if the current branch is missing commits from the default branch.
--force, -f	boolean	no	False	Overwrite changes made on Overleaf to push-only paths, which the project is meant to be the source of truth for.
--verbose	boolean	no	False	Enable verbose output.

calkit overleaf|ol pull

Bring collaborators' Overleaf writing back into the project.

Syncs in both directions, since Overleaf needs current figures to be worth writing against, then rebuilds the document from whatever came back and saves it.

Usage:

calkit overleaf|ol pull [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to pull from Overleaf, e.g., 'paper'. If not provided, all Overleaf publications will be pulled.

Options:

Option	Type	Required	Default	Description
--branch, -b	str	no		Switch to (or create) this branch before pulling. Useful when the default branch is protected, since pulling from Overleaf creates commits.
--yes, -y	boolean	no	False	Answer yes to all prompts, e.g., to run non-interactively.
--no-pull	boolean	no	False	Do not pull from Git and DVC beforehand.
--no-run	boolean	no	False	Do not run the pipeline after pulling.
--allow-stale	boolean	no	False	Pull even if the pipeline is out-of-date.
--any-branch	boolean	no	False	Pull even if the current branch is missing commits from the default branch.
--force, -f	boolean	no	False	Overwrite changes made on Overleaf to push-only paths, which the project is meant to be the source of truth for.
--verbose	boolean	no	False	Enable verbose output.

calkit hub|cloud

Interact with a Calkit hub.

Command	Description
get	Get a resource from the hub API.
login	Log in to a Calkit hub.
config	Work with per-hub credentials (tokens).

calkit hub|cloud get

Get a resource from the hub API.

Usage:

calkit hub|cloud get [OPTIONS] ENDPOINT

Arguments:

Argument	Type	Required	Default	Description
endpoint	str	yes		API endpoint

Options:

Option	Type	Required	Default	Description
--hub	str	no		URL of the hub to target, e.g., https://staging.calkit.io. Defaults to the working directory project's hub, if declared, else calkit.io.

calkit hub|cloud login

Log in to a Calkit hub.

First try a GET request to the /user endpoint to check if the user is already logged in. If not, perform OAuth device flow.

Usage:

calkit hub|cloud login [OPTIONS]

Options:

Option	Type	Required	Default	Description
--hub	str	no		URL of the hub to target, e.g., https://staging.calkit.io. Defaults to the working directory project's hub, if declared, else calkit.io.
--force, -f	boolean	no	False	Force logging in again even if already authenticated. Will store a new token in your local config.

calkit hub|cloud config

Work with per-hub credentials (tokens).

Usage:

calkit hub|cloud config COMMAND [ARGS]...

calkit scheduler|sch

Work with a job scheduler (SLURM or PBS).

Command	Description
batch	Submit a batch job through the scheduler associated with the env.
queue\|q	List scheduler jobs submitted via Calkit (across SLURM and PBS).
cancel	Cancel scheduler jobs by their name in the project.
logs	Get the logs for scheduler jobs by their name in the project.

calkit scheduler|sch batch

Submit a batch job through the scheduler associated with the env.

Duplicates are not allowed, so if one is already running or queued with the same name, we'll wait for it to finish. The only exception is if the dependencies have changed, in which case any queued or running jobs will be canceled and a new one submitted.

If the environment sets max_concurrent_jobs, submission waits until this project has fewer than that many jobs queued or running, so an iterated stage does not put all of its jobs into a shared cluster's queue at once.

Usage:

calkit scheduler|sch batch [OPTIONS] TARGET [ARGS...]

Arguments:

Argument	Type	Required	Default	Description
target	str	yes		The target to run. This can be a shell script or an executable.
args	str	no		Arguments for the target command, passed to the job script after the target.

Options:

Option	Type	Required	Default	Description
--name, -n	str	yes		Job name.
--environment, -e	str	yes		Calkit (scheduler) environment to use for the job.
--dep, -d	str	no		Additional dependencies to track, which if changed signify a job is invalid.
--out, -o	str	no		Non-persistent output files or directories produced by the job, which will be deleted before submitting a new job.
--option, -s	str	no		Additional options to pass to the scheduler submit command (no spaces allowed).
--setup	str	no		Shell setup command to run before launching the target (repeat for multiple commands).
--setup-file	str	no		Path to a JSON list of setup commands, used instead of --setup, since a path survives cmd.exe and a POSIX shell alike, and quoted commands don't.
--log-path	str	no		Output log path.
--command	boolean	no		Whether the target is a command instead of a script.
--env-default-options	choice(ignore, replace, merge)	no	replace	How to apply the environment's default scheduler options: 'replace' (default) uses env defaults only when no options were provided here; 'merge' prepends env defaults (the scheduler's last-occurrence wins, so explicit options still override); 'ignore' never applies env defaults.
--env-default-setup	choice(ignore, replace, merge)	no	replace	How to apply the environment's default setup commands: 'replace' (default) uses env defaults only when no setup commands were provided here; 'merge' prepends env defaults; 'ignore' never applies env defaults.

calkit scheduler|sch queue|q

List scheduler jobs submitted via Calkit (across SLURM and PBS).

Usage:

calkit scheduler|sch queue|q

calkit scheduler|sch cancel

Cancel scheduler jobs by their name in the project.

Usage:

calkit scheduler|sch cancel NAMES...

Arguments:

Argument	Type	Required	Default	Description
names	str	yes		Names of jobs to cancel.

calkit scheduler|sch logs

Get the logs for scheduler jobs by their name in the project.

If no names are given, every tracked job's log is shown.

Usage:

calkit scheduler|sch logs [OPTIONS] [NAMES...]

Arguments:

Argument	Type	Required	Default	Description
names	str	no		Names of the jobs to get logs for.

Options:

Option	Type	Required	Default	Description
--follow, -f	boolean	no	False	Follow the log output like tail -f.

calkit sync

Sync with external systems.

Command	Description
git	Sync the Git repository by pulling and then pushing.
dvc	Sync the DVC repository by pulling and then pushing.
all	Sync all registered systems.
import	Pull an imported file from where it came from.
overleaf	Sync folders with Overleaf.

calkit sync git

Sync the Git repository by pulling and then pushing.

Usage:

calkit sync git [OPTIONS]

Options:

Option	Type	Required	Default	Description
--no-check-auth	boolean	no	False

calkit sync dvc

Sync the DVC repository by pulling and then pushing.

Usage:

calkit sync dvc [OPTIONS]

Options:

Option	Type	Required	Default	Description
--no-check-auth	boolean	no	False

calkit sync all

Sync all registered systems.

Usage:

calkit sync all

calkit sync import

Pull an imported file from where it came from.

For a Git source this takes the latest on whatever the entry follows, which is its 'ref' if it names one and the repo's default branch otherwise, and records the commit it lands on. '--git-ref' changes what it follows, from then on and not just this once, so switching to a tag pins the import to that tag rather than quietly reverting to the default branch next time.

This is a one-way copy from the source, not a merge. An import records that a file came from somewhere else, so a local edit that survived a refresh would make the entry a lie about what is on disk -- but losing that edit silently would be worse, so a file that differs from what was last fetched is reported and left alone until '--force' says otherwise. The checksum recorded in '.calkit/imports.json' is what makes the edit visible.

What the fetch resolves to -- the commit, the checksum, the time -- is written to '.calkit/imports.json' rather than to 'calkit.yaml', which keeps only what a person declared. To pin an import, write the commit hash as its 'ref'. An entry written before that split carries its 'rev' in 'calkit.yaml'; refreshing it moves that across, so nothing has to be migrated by hand.

With '--all', every imported object is refreshed instead, whichever list it was recorded in, and they are committed together. One that can't be refreshed in place -- a dataset tracked by DVC, or a record named only by a DOI -- is reported and skipped rather than stopping the rest, and so is one whose source can't be reached, since a repo being down shouldn't leave every other import stale. Naming a single object that can't be refreshed is still an error, since that is what was asked for. With '--all' the command exits non-zero if anything was skipped.

Only imported paths for now, since that is the only kind of object an import records. An imported environment has no path of its own, so when 'calkit import environment' is finished this is where refreshing it belongs.

Usage:

calkit sync import [OPTIONS] [PATH]

Arguments:

Argument	Type	Required	Default	Description
path	str	no		Path of the imported object to refresh. Omit with --all.

Options:

Option	Type	Required	Default	Description
--all	boolean	no	False	Refresh every imported object in the project, across all artifact kinds. Ones that can't be refreshed in place are reported and skipped.
--git-ref	str	no		Branch, tag, or commit to follow from now on, for a file imported from a Git repo. Recorded, so later refreshes keep using it.
--force, -f	boolean	no	False	Overwrite even if the file has been edited since it was imported.
--no-commit	boolean	no	False	Do not commit changes to repo.

calkit sync overleaf

Sync folders with Overleaf.

Local edits are committed first, and documents changed on either side are rebuilt and saved with the sync.

Usage:

calkit sync overleaf [OPTIONS] [PATHS...]

Arguments:

Argument	Type	Required	Default	Description
paths	str	no		Paths to sync with Overleaf, e.g., 'paper/paper.pdf'. If not provided, all Overleaf publications will be synced.

Options:

Option	Type	Required	Default	Description
--no-commit	boolean	no	False	Do not create a commit in the project repo for this sync. Changes pulled from Overleaf are still applied, but are left staged so you can review or commit them yourself. Changes are always committed and pushed to Overleaf regardless.
--no-push	boolean	no	False	Do not push the changes to the main project remote. Changes will always be pushed to Overleaf.
--verbose	boolean	no	False	Enable verbose output.
--resolve, -r	boolean	no	False	Mark merge conflicts as resolved before committing.
--push-only, -P	boolean	no	False	Only push local files to Overleaf without pulling from Overleaf. Useful when initializing a new Overleaf project from local files.
--allow-stale	boolean	no	False	Sync even if the pipeline is out-of-date, which can send stale figures or results to Overleaf.
--any-branch	boolean	no	False	Sync even if the current branch is missing commits from the default branch.
--force, -f	boolean	no	False	Overwrite changes made on Overleaf to push-only paths, which the project is meant to be the source of truth for.
--no-build	boolean	no	False	Only sync source files, without rebuilding documents changed on Overleaf.
--upstream	boolean	no	False	When rebuilding, also run stages the build depends on.
--no-pull	boolean	no	False	Don't pull new commits from the project remote first, e.g., from a sync on the hub.