The command line¶
Every command of samplekit, as its --help gives it. samplekit COMMAND -h prints a shorter summary in the terminal.
General options¶
The options most commands share. Each command below says which of them it takes.
-v, --verbose: Also say which files were skipped, and which configuration is used-q, --quiet: Print no warning--at <WHEN>: Read the project as it was at a snapshot of its historyWHEN is a number from
samplekit log, the beginning of a snapshot's id, or a date such as 2026-09-12 or '2026-09-12 14:30'.--no-color: No colour in messages (also NO_COLOR or TERM=dumb)--rc <PATH>: Use this .samplekitrc instead of the nearest one--show-rc: Print the configuration and model a command would use-h, --help: Print help; -h for a compact summary-V, --version: Print version
samplekit¶
Sample data in plain Markdown: computed, current, tracked
Find, show, check, compute, export and plot the samples of a project. Given files or a folder and no table options, samplekit prints the path of each sample selected; -c or --profile shows a table instead. Alone at a terminal, samplekit opens the TUI; elsewhere it prints this help.
Paths and options may come before the command or after it: samplekit samples status and samplekit status samples read the same. The first word naming a command is the command, even where a file or a folder has its name: write that one status/ or ./status, or after the command.
samplekit [TARGET] [OPTIONS]
samplekit [TARGET] <COMMAND> [OPTIONS]
Commands:
list: List fields, tags and what .samplekitrc declaresstatus: Show which computed values are not current, and whycompute: Compute the values the project's model givesexplain: Explain where one value came fromopen: Open a sample's own files (images, reports) or the folder holding themview: Show each selected sample whole: its values, then its tables; --note adds the noteexport: Preview an export declared in .samplekitrc, a table or a figure; --write writes itplot: Draw a figure with matplotlib, in a window or to a filerun: Run a script the model declares on each sample, or the selection; what it changes is shown and askedvalidate: Report the defects of sample files; nothing is changedtag: Add, remove or rename tagslog: List the snapshots of the project's historydiff: Compare two states of the project, value by valuerestore: Put files back as the history kept them: the last change taken back, or a state namedremove: Delete sample files; the history keeps them, and restore gives them backrename: Rename a sample, its own files with it, and the links leading to itinit: Set up a project, or complete one that existsnew: Create a sample from what the project already knowsset: Change values of a sampletui: Open the TUI, the full-screen interface, on a folder;samplekitalone opens its start pagehelp: Print this message or the help of the given subcommand(s)
Arguments:
[TARGETS]...: Sample files or folders; the current folder when an option is given
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Shape:
-c, --columns <COLUMNS>: Columns as FIELD[:PRECISION][=NAME]; repeat or comma-separate. NAME titles the column on the terminal and in a document, and names its columns in a CSV, TSV or JSON file: young_modulus=E writes E_value and E_uncertainty. A NAME holding a comma is quoted: young_modulus='Modulus, E'--profile <NAME>: Show the table a profile declared in .samplekitrc gives. It sets the columns, the order, the groups and the precision, and each option written beside it overrides its part: -c the columns, -s the order, --group the groups, --precision the digits--summary: Summarise each column instead of listing the samples--group <FIELDS>: One table per value of these fields, comma-separated, or per combination of values; with --summary, a summary per group
Presentation:
--style <STYLE>: Render in this style, declared in .samplekitrc, instead of [render] style: its unit spellings, its symbols and how it writes a property--precision <SPEC>: Precision of every numeric column, such as .3f; a column's own FIELD:PRECISION wins--table-style <STYLE>: Draw a plain or boxed table--width <WIDTH>: Assume this terminal width
Output:
--csv: Print CSV instead of a table--tsv: Print TSV instead of a table--json: Print JSON instead of a table--status: Add a state column: what in each row is not current-o, --output <PATH>: Write to this file instead of printing; '-' prints--save <KIND=NAME>: Save what the table shows in the project's .samplekitrc, under NAME: query=NAME the filter, profile=NAME the columns, the sort and the groups, export=NAME both and an export written to out/NAME.csv (--tsv or --json for another format). Nothing is printed but the lines added; a name already declared is refused--write: Write the --output file, or what --save adds; without it, a preview, then the question apply these changes? [y/N]--accept <STATES>: States a write from values not current may hold and exit 0: outdated, edited[:NAME,…], failed, never_computed
General options (described once): -v, --verbose, -q, --quiet, --at, --no-color, --rc, --show-rc, -h, --help, -V, --version.
Examples:
# Print the path of every sample a filter selects
samplekit samples/ -f 'elongation > 20'
# A table of chosen fields, sorted
samplekit samples/ -c material,tensile_strength -s -tensile_strength
# A table per material, each headed by it
samplekit samples/ -c width,thickness --group material
# A table declared in .samplekitrc
samplekit samples/ --profile overview
# Computed values that are not current, and why
samplekit samples/ status
# Compute what is not current, and write it
samplekit samples/ compute --write
# A command's own page, with its examples
samplekit help compute
samplekit list¶
List fields, tags and what .samplekitrc declares
samplekit [TARGET] list [KIND] [OPTIONS]
Arguments:
[KIND_OR_TARGET]: Category to enumerate (fields, tags, queries, profiles, exports, figures, scripts, files or skipped), or a target when used alone[TARGETS]...: Sample files or folders, after a category; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What the collection holds and declares
samplekit samples/ list
# Every field a filter, a column or a sort can name
samplekit samples/ list fields
# Every tag in use
samplekit samples/ list tags
# The files the scan skipped, and why
samplekit samples/ list skipped
samplekit status¶
Show which computed values are not current, and why
samplekit [TARGET] status [OPTIONS]
Arguments:
[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort--timeout <SECONDS>: Stop the model's loading past this, in seconds; 60 by default
Presentation:
--table-style <STYLE>: Draw a plain or boxed table--width <WIDTH>: Assume this terminal width
Output:
--exit-code: Exit 2 when any value is not current, as git diff --exit-code does: a check for continuous integration. A value waiting for an input nobody entered does not fail it. Without --exit-code, status exits 0 whatever it lists--accept <STATES>: With --exit-code, states that do not fail the check: edited, or edited:NAME,… for those values alone; waiting never does--json: Print JSON: one object per value not current
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Values outdated, failed, edited or never computed, and why
samplekit samples/ status
# Only in the samples a filter selects
samplekit samples/ status -f 'material == steel'
# Exit 2 when anything is not current: a check for a script
samplekit samples/ status --exit-code
samplekit compute¶
Compute the values the project's model gives
samplekit [TARGET] compute [OPTIONS]
Arguments:
[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort-p, --properties <VALUES>: Compute only these values (properties, or table columns as table.column) and the inputs they need. The values computed from them are left outdated, for a compute without -p. Repeat or comma-separate--rerun: Also run values that are current: after a formula changed, or when one reads data outside the samples--force: Also run edited values, giving them back to their formula--timeout <SECONDS>: Stop a formula that runs longer than this, in seconds: its value is failed, and the others run
Presentation:
--table-style <STYLE>: Draw a plain or boxed table--width <WIDTH>: Assume this terminal width
Output:
--write: Compute and write the files, showing before and after, asking nothing--show-output: Show what the model prints as it prints it; it is always kept in the run's log
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# List what would run, and why; asked, compute it, then asked, write it
samplekit samples/ compute
# Compute what is outdated or never computed, and write it
samplekit samples/ compute --write
# Only these values, with the inputs they need
samplekit samples/ compute -p area,curve.stress --write
# Also the values that are current: after a formula changed
samplekit samples/ compute --rerun --write
# Also the values typed over their formula, given back to it
samplekit samples/ compute --force --write
# Every formula of the selected samples
samplekit samples/ compute --rerun --force --write
# Also show what the model prints, as it prints it
samplekit samples/ compute --write --show-output
samplekit explain¶
Explain where one value came from
samplekit [TARGET] explain <FIELD> [OPTIONS]
Arguments:
[TARGET|FIELD]...: Sample files or folders, or files SampleKit wrote, and the field to explain: the one word naming no file
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
Presentation:
--style <STYLE>: Render in this style, declared in .samplekitrc, instead of [render] style: its unit spellings, its symbols and how it writes a property--precision <SPEC>: Precision of every numeric column, such as .3f; a column's own FIELD:PRECISION wins
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Where a value came from: its inputs and their states
samplekit samples/steel-01.md explain area
# The same for one table cell
samplekit samples/steel-01.md explain 'curve.stress[0.2]'
samplekit open¶
Open a sample's own files (images, reports) or the folder holding them
samplekit [TARGET] open [PATTERN] [OPTIONS]
Arguments:
[TARGET|PATTERN]...: Sample files or folders, and a glob naming their files to open, such as '*.jpg': the one word naming no file; more than five ask first
Options:
--navigate: Open the folder holding them in the file manager instead--edit: Open the sample's own file, with the application the system gives its kind
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Where [collection] files is declared: the sample's file whose name matches, in the system's viewer
samplekit samples/steel-01.md open '*.jpg'
# Where [collection] files is declared: the folder holding its files, in the file manager
samplekit samples/steel-01.md open --navigate
# The sample's own file, with the system's application for it
samplekit samples/steel-01.md open --edit
# Where [collection] files is declared: every sample's files, and those belonging to none
samplekit samples/ list files
samplekit view¶
Show each selected sample whole: its values, then its tables; --note adds the note
samplekit [TARGET] view [OPTIONS]
Arguments:
[TARGETS]...: Sample files or folders, the current folder by default. A word that is no file and names a table of the samples selected shows that table alone: samplekit samples/steel-01.md view curve
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Presentation:
--style <STYLE>: Render in this style, declared in .samplekitrc, instead of [render] style: its unit spellings, its symbols and how it writes a property--precision <SPEC>: Precision of every numeric column, such as .3f; a column's own FIELD:PRECISION wins--table-style <STYLE>: Draw a plain or boxed table--width <WIDTH>: Assume this terminal width
Output:
--note: Print each sample's note after its values and tables--csv: Print a table named as CSV--tsv: Print a table named as TSV--json: Print a table named as JSON-o, --output <PATH>: Write a table named to this file, its extension naming the format; '-' prints--write: Write the --output file; without it, a preview, then the question apply these changes? [y/N]--accept <STATES>: States a write from values not current may hold and exit 0: outdated, edited[:NAME,…], failed, never_computed
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# The sample whole: its values, then its tables unfolded
samplekit samples/steel-01.md view
# Each sample a saved query selects, with its note
samplekit samples/ view --query ductile --note
# One table alone, its rows written to a file
samplekit samples/steel-01.md view curve -o curve.csv --write
samplekit export¶
Preview an export declared in .samplekitrc, a table or a figure; --write writes it
samplekit [TARGET] export <EXPORT> [OPTIONS]
Arguments:
<EXPORT>: An export declared in .samplekitrc[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Presentation:
--precision <SPEC>: Precision of every numeric column, such as .3f, instead of what the profile and the project declare: an export is written at the declared precision, and this asks for another one, or for more digits: --precision .6e--style <STYLE>: Spell the units in this style instead of as the sample files write them: plain for the forms [unit.*] declares for the screen, a spreadsheet's headers in Unicode, or a style declared in .samplekitrc
Output:
--status: Add a state column: what in each row is not current--accept <STATES>: States a write from values not current may hold and exit 0: outdated, edited[:NAME,…], failed, never_computed-o, --output <PATH>: Write to this file instead of the declared one; '-' prints--write: Write the file, replacing it; without it, a preview, then the question apply these changes? [y/N]
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What a declared export would write, and where; --write writes it
samplekit export paper
# Print it instead
samplekit export paper -o -
# Write it elsewhere, replacing that file
samplekit export paper -o results.tex --write
samplekit plot¶
Draw a figure with matplotlib, in a window or to a file
samplekit [TARGET] plot <FIGURE> [OPTIONS]
samplekit [TARGET] plot -x <FIELD> -y <FIELD> [OPTIONS]
Arguments:
[FIGURE]: A figure .samplekitrc or the model declares; with -x and -y, a sample file or folder[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Shape:
-x, --x <FIELD>: The field on the x axis, for a figure not declared: a property, an attribute, or a table's cell or column-y, --y <FIELD>: The field on the y axis--group <FIELDS>: One series per value of these fields, comma-separated, or per combination of values; replaces the figure's own--kind <KIND>: scatter, line, step, bar or box; replaces the figure's own[possible values: scatter, line, step, bar, box]
Presentation:
--title <TEXT>: The figure's title, instead of its name--x-label <TEXT>: The x axis label, instead of the field's symbol and unit--y-label <TEXT>: The y axis label, instead of the field's symbol and unit--style <STYLE>: The declared style whose symbols and units label the axes; plain otherwise--x-limits <LOW,HIGH>: The x axis bounds, LOW,HIGH; auto leaves one free: 0,100 or 0,auto--y-limits <LOW,HIGH>: The y axis bounds, LOW,HIGH; auto leaves one free--x-scale <SCALE>: The x axis scale: linear, log or symlog[possible values: linear, log, symlog]
--y-scale <SCALE>: The y axis scale: linear, log or symlog[possible values: linear, log, symlog]
--aspect <ASPECT>: equal draws one unit as long on both axes; auto lets them differ[possible values: equal, auto]
--legend <PLACE>: Where the legend goes: best, outside, none, or a matplotlib place such as "upper left"[possible values: best, outside, none, "upper right", "upper left", "lower left", "lower right", right, "center left", "center right", "lower center", "upper center"]
--figsize <W,H>: The figure's width and height in centimetres, as 18,12--no-project-style: Draw with matplotlib's own settings, leaving out [matplotlib] of .samplekitrc
Output:
-o, --output <PATH>: Write the figure to this file, in the format its extension names; without it, a window opens--write: Write the --output file, replacing it; without it, a preview, then the question apply these changes? [y/N]--accept <STATES>: States a write from values not current may hold and exit 0: outdated, edited[:NAME,…], failed, never_computed
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Open a declared figure, or the model's, in a matplotlib window
samplekit samples/ plot curves
# Draw two fields against each other, one series per material
samplekit samples/ plot -x yield_strength -y tensile_strength --group material
# A declared figure of the samples a saved query selects, one series per sample
samplekit samples/ plot curves --query ductile --group name
# Write it to a file instead, as over SSH
samplekit samples/ plot curves -o curves.pdf --write
samplekit run¶
Run a script the model declares on each sample, or the selection; what it changes is shown and asked
samplekit [TARGET] run <SCRIPT> [OPTIONS]
Arguments:
[SCRIPT]: A script the model declares: samplekit list scripts names them[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort--timeout <SECONDS>: Stop the script if it runs longer than this, in seconds: nothing is written
Shape:
--set <NAME=VALUE>: One of the script's options, NAME=VALUE, read as the script's signature types it: --set factor=0.8. Repeatable; samplekit list scripts names each script's options
Presentation:
--style <STYLE>: The style what the script returns is written in; [render] style's otherwise
Output:
--write: Write what the script changes, asking nothing
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# The model's scripts, what each acts on, and its options
samplekit list scripts
# Run a script on each sample, an option set; what it changes is shown, then asked
samplekit samples/ run classify --set limit=15
# Write what it changes without asking
samplekit samples/ run classify --write
# A script of the selection, run once: what it prints is shown
samplekit run ranking
samplekit validate¶
Report the defects of sample files; nothing is changed
samplekit [TARGET] validate [OPTIONS]
Arguments:
[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold--timeout <SECONDS>: Stop the model's loading past this, in seconds; 60 by default
Output:
--json: Print JSON: one object per finding
General options (described once): --at, -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# The defects and notes of every sample; nothing is changed
samplekit samples/ validate
# The same for one sample
samplekit samples/steel-01.md validate
samplekit tag¶
Add, remove or rename tags
samplekit [TARGET] tag add <TAG> [OPTIONS]
samplekit [TARGET] tag remove <TAG> [OPTIONS]
samplekit [TARGET] tag rename <OLD> <NEW> [OPTIONS]
Commands:
tag add: Add a tag to the samples selectedtag remove: Remove a tag from the samples selectedtag rename: Rename a tag in the samples selectedtag help: Print this message or the help of the given subcommand(s)
General options (described once): --no-color, --rc, --show-rc, -h, --help.
Examples:
# Show which samples would gain the tag; nothing is written
samplekit samples/ tag add reference -f 'material == steel'
# Remove a tag from one sample
samplekit samples/steel-01.md tag remove reference --write
# Rename a tag across the collection
samplekit samples/ tag rename old_name new_name --write
samplekit tag add¶
Add a tag to the samples selected
samplekit [TARGET] tag add <TAG> [OPTIONS]
Arguments:
<NAME>: The tag[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Show which samples would gain the tag; nothing is written
samplekit samples/ tag add reference -f 'material == steel'
# Add it
samplekit samples/ tag add reference -f 'material == steel' --write
samplekit tag remove¶
Remove a tag from the samples selected
samplekit [TARGET] tag remove <TAG> [OPTIONS]
Arguments:
<NAME>: The tag[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Show which samples would lose the tag; nothing is written
samplekit samples/ tag remove reference
# Remove it from one sample
samplekit samples/steel-01.md tag remove reference --write
samplekit tag rename¶
Rename a tag in the samples selected
samplekit [TARGET] tag rename <OLD> <NEW> [OPTIONS]
Arguments:
<OLD>: The tag to rename<NEW>: Its new name[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# Show where the tag would be renamed; nothing is written
samplekit samples/ tag rename old_name new_name
# Rename it across the collection
samplekit samples/ tag rename old_name new_name --write
samplekit log¶
List the snapshots of the project's history
samplekit [TARGET] log [OPTIONS]
Arguments:
[TARGETS]...: Files or folders whose changes to list; the whole project by default
Options:
--script <WHEN>: Print the Python script that made a snapshot, as it ranWHEN names the snapshot as --at does: a number from
samplekit log, the beginning of its id, or a date.
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
Output:
--export: Write an account of the history in Markdown, to share beside the filesEach snapshot with when, what made it, every file it changed and the script kept beside it. Printed, or written to -o FILE with --write.
-o, --output <PATH>: Write the account to this file; '-' prints--write: Write the --output file, replacing it; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
General:
--at <WHEN>: Start the list at this snapshot, the newer ones left out; the numbers stay those of the whole historyWHEN is a number from
samplekit log, the beginning of a snapshot's id, or a date such as 2026-09-12 or '2026-09-12 14:30'.
Examples:
# Every snapshot of the project's history, newest first
samplekit log
# Those that changed one sample
samplekit samples/steel-01.md log
# An account of the history in Markdown, to share beside the files
samplekit log --export -o HISTORY.md --write
# The Python script that made snapshot #2 of the list, as it ran
samplekit log --script 2
samplekit diff¶
Compare two states of the project, value by value
samplekit [TARGET] diff [OPTIONS]
Arguments:
[TARGETS]...: Files or folders to compare; the whole project by default
Options:
--from <WHEN>: The state compared from; by default the snapshot before the one --to names, or before the last change keptWHEN is now, a number from
samplekit log, the beginning of a snapshot's id, or a date such as 2026-09-12 or '2026-09-12 14:30'. Without --from or --to, diff shows the last change kept: that snapshot against the one before it.--to <WHEN>: The state compared to; now with --from alone, the last change kept without eitherWHEN is named as --from is.
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# The last change SampleKit kept, value by value
samplekit diff
# The last change kept of one sample
samplekit samples/steel-01.md diff
# What changed since, outside SampleKit
samplekit diff --from 1
# Between two dates, value by value
samplekit diff --from 2026-09-01 --to 2026-09-12
samplekit restore¶
Put files back as the history kept them: the last change taken back, or a state named
samplekit [TARGET] restore [OPTIONS]
Arguments:
[TARGETS]...: Files or folders to put back; the whole project by default
Options:
--at <WHEN>: The state to put them back to; by default, the last change SampleKit wrote on this computer is taken back, keeping what was changed since, or a file deleted or changed outside SampleKit comes back as last keptWHEN is a number from
samplekit log, the beginning of a snapshot's id, or a date such as 2026-09-12 or '2026-09-12 14:30'.
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
Output:
--write: Write the files; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What taking back the last change kept would do; nothing is written
samplekit restore
# Take back the last change kept of one sample
samplekit samples/steel-01.md restore --write
# Put the samples back as snapshot #3 of samplekit log kept them
samplekit samples/ restore --at 3 --write
samplekit remove¶
Delete sample files; the history keeps them, and restore gives them back
samplekit [TARGET] remove [OPTIONS]
Arguments:
[TARGETS]...: Sample files or folders; the current folder by default
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold-s, --sort <FIELDS>: Sort by these fields, the first deciding first; repeat or comma-separate. A leading - sorts that field in descending order: -s material,-tensile_strength-r, --reverse: Reverse the sort
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What deleting one sample would do; nothing is written
samplekit samples/steel-01.md remove
# Delete the samples a filter selects; samplekit restore gives them back
samplekit samples/ remove -f 'tags has scrapped' --write
samplekit rename¶
Rename a sample, its own files with it, and the links leading to it
samplekit FILE rename <NEW> [OPTIONS]
Arguments:
<NEW>: The sample's new name: its file's, without the folder or.md[TARGETS]...: The sample file to rename
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What renaming one sample would do, its links with it; nothing is written
samplekit samples/steel-01.md rename steel-04
# Rename it, its own files and every link leading to it
samplekit samples/steel-01.md rename steel-04 --write
samplekit init¶
Set up a project, or complete one that exists
samplekit [DIRECTORY] init [OPTIONS]
Arguments:
[DIRECTORY]: The folder to set up; the current one by default
Options:
--example: Start from the example project, a model with one formula of each kind, rather than an empty one--no-model: An empty project without a model: every value typed in the samples--model <PATH>: Name a model file one already has in .samplekitrc, rather than write one to fill in; nothing is copied--no-venv: Make no Python environment, nor install samplekit in one
Output:
--write: Write the files; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# At a terminal, a few questions, then what it will write, on a yes
samplekit init
# An empty project, its model to fill in, and an environment
samplekit init --write
# The example project, one formula of each kind, in another folder
samplekit example/ init --example --write
samplekit new¶
Create a sample from what the project already knows
samplekit [FOLDER] new <NAME> [FIELD=VALUE]... [OPTIONS]
Arguments:
<NAME>: The new sample's name; its file takes the same stem[FIELD=VALUE]...: Values to fill in now, as field=value; repeatable
Options:
--keep <SAMPLE> <FIELDS>: Take these fields from another sample, as they are, and nothing else:--keep samples/steel-01.md width,grade--into <DIRECTORY>: The folder to write it in, or the path of the file itself; by default beside the sample --keep names, in samples/ where there is one, or in the current folder
Output:
--write: Write the file; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What the file would hold: what you give here, named by its file
samplekit new steel-02
# Write it with values already filled in
samplekit new steel-02 material=steel width=12.5 --write
# Take a value another specimen measured, with its readings, and an attribute; nothing else
samplekit samples/ new steel-02 --keep samples/steel-01.md width,grade --write
samplekit set¶
Change values of a sample
samplekit [TARGET] set [FIELD=VALUE]... [OPTIONS]
Arguments:
[TARGET|FIELD=VALUE]...: Sample files or folders, and what to change, as field=value: a word holding = is a change. An uncertainty is width.u, readings width.readings=12.51,12.52, a table cell curve.force[0.2], the name the file shows, name=…, and the note below the frontmatter, note=…
Options:
--add-row <TABLE>: Add a row to this table instead, the assignments naming its columns
Selection:
-f, --filter <EXPR>: Keep the samples an expression selects. Repeatable: every --filter and every --query must hold.elongation > 20, material == steel, material == "cast iron", tensile_strength > yield_strength, material in (steel, copper), tags has reference, curve where (strain > 1 && stress < 300), elongation is missing. Combine with &&, || and ! and parentheses, and quote the whole expression for the shell. Every form: https://zelyph.github.io/SampleKit/latest/reference/filters.html
--query <NAME>: Keep the samples a query saved in .samplekitrc selects. Repeatable: every --filter and every --query must hold
Output:
--write: Write the change; without it, a preview, then the question apply these changes? [y/N]
General options (described once): -v, --verbose, -q, --quiet, --no-color, --rc, --show-rc, -h, --help.
Examples:
# What the change would make outdated; nothing is written
samplekit samples/steel-01.md set thickness.readings=1.991,1.994,1.989
# Write it
samplekit samples/steel-01.md set thickness.readings=1.991,1.994,1.989 --write
# Several fields at once, written together or not at all
samplekit samples/steel-01.md set grade=S275 direction=T --write
# One cell of a table, addressed by its index
samplekit samples/steel-01.md set 'curve.force[0.2]=9.52' --write
# A new measurement: one row, the model computes its other columns
samplekit samples/steel-01.md set --add-row curve strain=0.1 force=5.13 --write
samplekit tui¶
Open the TUI, the full-screen interface, on a folder; samplekit alone opens its start page
samplekit [DIRECTORY] tui [OPTIONS]
Arguments:
[DIRECTORY]: The folder to open; the current one by default
General options (described once): --no-color, --rc, --show-rc, -h, --help.
Examples:
# The TUI on a folder: its samples, their values and states
samplekit samples/ tui
# At a terminal, the start page: the project here, the recent ones, a new one
samplekit