Using the trudag CLI tool
trudag is the Trustable project's tooling solution for applying the Trustable Methodology.
You don't need to use trudag to apply Trustable, but its likely to be the easiest route for greenfield projects.
This documentation is intended to explain how to use the tool to apply the Trustable Methodology.
To this end, this page is structured to mirror the methodology documentation.
If you haven't read that yet, please read it first.
For specific technical help, check trudag --help, the API reference pages or ask in our TSF Matrix chat room.
Model
Trudag stores statements as markdown files that are uniquely named within a project's git repository.
The name of the file serves as the Statement's identifier (without the .md extension).
Each statement file contains a small amount of frontmatter and the Statement itself.
An illustrative example, SUN-BRIGHTNESS.md, is shown below:
---
# Is the item Normative or Informative.
normative: True
# Used to specify a Validator and its arguments.
evidence:
type: "name"
configuration: {}
# Used to specify Reference artefacts.
references:
- type: "file"
path: "path/to/ref"
# Collection of SME scores.
score:
Neil: 0.8
Rachel: 0.6
---
The Sun is bright.
Statement files are intended for human editing only.
They are read by trudag, but trudag will never write to existing Statement files.
Warning
Statement identifiers may not contain the " character (This is a limitation of the pydot library currently used for parsing .dot).
The links between items are stored in a .dot file, .dotstop.dot, which is placed in the top-level of a project's git repository.
This file is intended to be human-readable (in particular when reading diffs in a version control system) but should not be edited by hand.
An example .dotstop.dot file is shown below:
# This file is automatically generated by dotstop and should not be edited manually.
# Generated using trustable 2025.3.14.
digraph G {
"SUN-BRIGHTNESS" [sha="0d200951"];
"SUN-TEMPERATURE" [sha="7dh394h"];
"SUN-BRIGHTNESS -> "SUN-TEMPERATURE" [sha="h3d730s1"]
}
trudag uses a strict subset of the DOT language.
That means trudag output is guaranteed to be valid DOT and, by extension, compatible with popular libraries like networkx,
tools like gephi and,
of course, graphviz itself.
Methodology
This section explains how trudag can be used to apply the Trustable Methodology.
Recall that the methodology is defined in terms of several distinct and unordered stages:
- Setting Expectations
- Providing Evidence
- Documenting Assumptions
- Recording Reasoning
- Assessing Confidence
When moving between any two stages,
the Modification guidance must also be considered.
The next section discusses how trudag is used in each of these stages.
Setting Expectations
To begin a trudag project, run
This will create an empty dotstop database. (You can optionally pass a name for the database by trudag init -n NAME)
Applying the TSF
If you're planning to use the Trustable Methodology to apply TSF, you can import the TSF artifact into your project (available at https://gitlab.eclipse.org/eclipse/tsf/tsf/-/releases).
To populate this database, run
to create your first item. This will create the item SUN-COLOR, stored in the markdown file /path/to/desired/location/SUN-COLOR.md.
The first argument is the "document" prefix.
Items with the same prefix are grouped together for presentation purposes.
This has no other effect.
The second argument is the item name.
It may not contain the - character, which is reserved for document prefixes.
Open the file and write your Expectation, following the example in the model section.
You can also add an existing item inside the project directory by:
This will add the SUN item file to your database and allow you to perform further operations.
Providing Evidence
Recall the methodology introduces two classes of Evidence:
- Evidence argued on the basis of a Reference
- Evidence argued on the basis of a Validator
These two classes are addressed in turn in the following subsections.
References
To provide a Reference, add a references field to the frontmatter of an Item.
You may provide multiple references as an array. For each reference you should specify a type.
You will also need to provide additional fields that are dependent on the type of reference you are using.
Check the documentation for the specific reference type you are interested in.
Tip
You can define custom references outside of the builtin types.
The following sections describe the builtin types and their uses:
Type: LocalFileReference
References to Artifacts that are regular local files, in the git sense.
This means any regular file that is present in the git tree for the current commit of the local repository.
For example, a reference to a locally stored text file:
Type: GitlabFileReference
References to Artifacts that are regular files in a remote GitLab repository.
For example, a reference to the README.md for the official GitLab repository:
---
references:
- type: "gitlab"
url: "gitlab.com"
id: gitlab-org/gitlab
path: README.md
ref: main
---
This Statement has a Gitlab reference.
Validators
To indicate a Statement should be automatically Validated, add an evidence field to the frontmatter of an Item.
You may only provide a single Validator against a Statement.
You should specify a type (a string) and a configuration (a dictionary of any schema).
The fields of configuration are passed directly to the Validator function.
Out of the box, trudag does not contain any Validators.
Check out how to write your own here.
The following is an example of using a validator named my_custom_validator:
---
evidence:
type: my_custom_validator
configuration:
arg1: 123
some_path: docs/validators.md/process/personnel.md
---
Item body
This results in my_custom_validator being used to score the item with the stated configuration.
Documenting Assumptions
From the perspective of our data model,
Assumptions are just Items without Children or Artifacts.
The same is true in trudag.
Any Item without Children or Artifacts will be automatically identified as an Assumption and scored appropriately.
Recording Reasoning
To construct an argument, use trudag to link different Statements together.
For instance, to create a link from the new Expectation SUN-COLOR to the existing Evidence SUN-TEMPERATURE, run
This command will automatically update the dotstop database to include the link.
Remember, you can Qualify Assertions using the references field exactly as for Evidence.
Assessing Confidence
In the methodology, the assessment of confidence in XYZ was broken into two stages. First, Evidence is subjected to SME review. Secondly, all validators are executed and the scores for all requests are calculated recursively from the Evidence.
SME review
To provide an SME review for an Evidence Statement on the basis of its References,
add a score field and populate it with key-value pairs of assessor names and scores.
Info
The names of SMEs are not currently used by trudag.
To aid with traceability we suggest that:
- Names are unique to an individual and each individual uses only one name.
- Names coincide with usernames in the context they are used, e.g. GitHub or GitLab users.
Validation and Calculation
To recursively calculate scores from Evidence and execute all validators, run
This command will print a summary of scores to the console.
This is not a very nice way to consume the data as a human being.
To produce a markdown report that can be rendered using mkdocs, run
You may also disable validators by passing --no-validate for commands that calculate scores,
or use --concurrent-validation to enable validations to run concurrently, which is particularly
beneficial if your validators are primarily I/O bound.
To monitor your trustable scores over time consider setting up a data store.
Leverage your historical data to include figures in the report that show the change in scores over time.
To do this use trudag publish --figures.
Tip
The environment created by running poetry install --with dev; eval $(poetry env activate); is guaranteed to have all the mkdocs plugins and extensions needed to correctly render the generated report.
Configuring report
For publishing, item files can be configured through the publish field.
All of the options are shown below:
---
publish:
group: "group_a" # Group, used for ordering items
order: 100 # Priority value, used for ordering items
---
By default, the items in the report are ordered by the item name.
You can order the items using the group and order fields.
Using group would group the items with the same group name. Group themselves are ordered by the group name.
Using order would choose the priority of an item within individual groups. It is sorted from low to high values, where the low value would be shown at the top of the group.
If group is unspecified, the item will be in an unnamed group, and this group is shown at the top of the document prefix in the report.
If order is unspecified, those items would be pushed to the top of the group.
If the two items has the same group and order, it will fall back to be sorted by name.
Usage
This section describes briefly how to use trudag. For additional information or options on any
of the commands used, append --help directly after the command.
Tip
Remember, an example process for managing modifications is provided here.
trudag provides all of the functionality necessary to follow this process.
Using the Shell
trudag shell can also be used to initialise a session in which all of the commands below can be run
whilst keeping the graph in context. This can increase the speed of workflows, particularly for large graphs,
and enables both command and item completion. To use the shell to operate on the needs graph, run trudag --needs shell.
Commands in the shell should be inputted in the same way, except the leading trudag is removed.
Every command in the shell updates the dotfile, rather than at the end of the shell session.
Command history persists between sessions on a per-project basis,
history files are stored in a directory trudag/ in $XDG_DATA_HOME if defined, otherwise $HOME/.local/share/.
Internal REPL commands are prefixed by :, use :help for information on them.
External terminal commands can also be run inside the shell by prefixing them with ! .e.g. !ls.
Use ctrl+D or :q to exit the shell.
Adding new items
To create new items use the following:
Inspecting items
To inspect specific items or links, you can use the
and
subcommands respectively.
For a big-picture view, use plot to inspect the entire graph (defaults to svg format):
Reviewing items
Review used to track whether the item is included in our Trustable argument
and up-to-date. It is conducted by a human using the command:
or to review multiple items at once
Note: To mark both the item (or all items provided) and all related links use
the flag --link:
Clearing suspect items
When a linked Item is modified, trudag will report a Suspect link. This
indicates fingerprint link between two items is no longer valid, necessitating a
reevaluation to determine whether its linkage is still relevant.
Linting a Trustable graph
To view the Suspect status of all items and links in a graph, run the manage lint subcommand as shown below (with an example output).
>> trudag manage lint
WARNING: Suspect Link: SUN-BRIGHTNESS -> SUN-TEMPERATURE
WARNING: Unreviewed Item: SUN-BRIGHTNESS
Generating a report
To generate a Trustable report, run the publish command:
By default, report files will be generated in a directory named docs/trustable.
Then you can either view the markdown files directly, or use mkdocs serve to serve the page locally if you have
mkdocs installed.
Data Store
Long-term maintenance entails trend analysis, which depends on data about the project's state.
To perform trend analysis on your TSF project, data about the graph's state must be stored persistently.
In aid of this trudag is able to interface with an external data store.
Please see the data store for guidance.
Needs
A "needs" graph captures unresolved assumptions that a project should satisfy.
It is stored alongside the main dotstop graph in a .needs.dot file.
To initialise a needs graph, run:
Items in the needs graph are created and managed using the --needs flag:
Moving items between graphs
To move an existing item from the dotstop graph into the needs graph:
To move an item from the needs graph back to the dotstop graph:
Warning
An item can only be moved if it has no links (parents or children) in its source graph. Remove any links before moving.
Migration from doorstop
Though doorstop was previously a supported backend, as trudag has evolved, it can no longer be supported. If you still use a doorstop database, use release v2025.05.29, the last release that supported the migration command.
Ignoring Specific Files or Folders
Sometimes you may want to exclude certain files or directories from processing.
To do this, we provide a .trustableignore file (located either at the git
repository root or in the same directory as your .dotstop.dot file).
This file allows you to explicitly tell trudag which files or folders to
ignore.
Note: Globbing (wildcard patterns like
*or?) is not supported.
In some cases, you might have files with the same name across different
repositories.
If a Markdown file happens to share a name with an item in your trustable graph,
this can cause conflicts.
To prevent that, simply add the file path (relative to the git root) to your
.trustableignore.
Example: Ignoring a Specific File
If you have a file named TRUSTABLE-SOFTWARE.md inside a folder that’s
not related to TSF, add the following line to your .trustableignore file:
To Ignore an entire folder