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 history

    WHEN 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 declares

  • status: Show which computed values are not current, and why

  • compute: Compute the values the project's model gives

  • explain: Explain where one value came from

  • open: Open a sample's own files (images, reports) or the folder holding them

  • view: Show each selected sample whole: its values, then its tables; --note adds the note

  • export: Preview an export declared in .samplekitrc, a table or a figure; --write writes it

  • plot: Draw a figure with matplotlib, in a window or to a file

  • run: Run a script the model declares on each sample, or the selection; what it changes is shown and asked

  • validate: Report the defects of sample files; nothing is changed

  • tag: Add, remove or rename tags

  • log: List the snapshots of the project's history

  • diff: Compare two states of the project, value by value

  • restore: Put files back as the history kept them: the last change taken back, or a state named

  • remove: Delete sample files; the history keeps them, and restore gives them back

  • rename: Rename a sample, its own files with it, and the links leading to it

  • init: Set up a project, or complete one that exists

  • new: Create a sample from what the project already knows

  • set: Change values of a sample

  • tui: Open the TUI, the full-screen interface, on a folder; samplekit alone opens its start page

  • help: 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 selected

  • tag remove: Remove a tag from the samples selected

  • tag rename: Rename a tag in the samples selected

  • tag 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 ran

    WHEN 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 files

    Each 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 history

    WHEN 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 kept

    WHEN 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 either

    WHEN 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 kept

    WHEN 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