VIAT(1) viat Manual VIAT(1)
NAME
viat - A tool for managing virtual file attributes.
SYNOPSIS
viat [OPTIONS] COMMAND [ARGS]...
DESCRIPTION
A tool for managing virtual file attributes.
In short, viat allows recording file attributes in a plain text file, by default
TOML.
OPTIONS
--skip-validation
Disable schema validation.
--version
Show the version and exit.
COMMANDS
viat get [OPTIONS] PATH ATTR
Retrieve a stored attribute for a tracked file.
Options:
-r, --raw Do not quote strings.
--help Show this message and exit.
viat get-all [OPTIONS] PATH
Retrieve all stored attributes for a tracked file.
Options:
--help Show this message and exit.
viat init [OPTIONS]
Initialize a new vault.
Options:
--help Show this message and exit.
viat mv [OPTIONS] SRC DEST
Move a file along with its metadata.
Options:
-f, --force Move even if the destination exists.
--help Show this message and exit.
viat rm [OPTIONS] PATH
Remove a file along with its metadata.
Options:
--help Show this message and exit.
viat set [OPTIONS] PATH ATTR VALUE
Update a stored attribute for a tracked file.
Unless the --raw parameter is given, we treat the value as JSON.
Options:
-r, --raw Treat the value like a string rather than as JSON.
--help Show this message and exit.
viat shell-export [OPTIONS]
Print the attributes for all tracked files in a table suitable for shell
scripting.
We list only the attributes that correspond to valid variable names
according to [a-zA-Z_][a-zA-Z_0-9]*.
Example:
path=path1 key1=value11 key2=value2
path=path2 key1=value21 key2=value22
Options:
--path-var TEXT Name of the variable storing the file's path.
--help Show this message and exit.
viat stale [OPTIONS]
Print out the paths with storage entries that are not tracked.
Options:
-j, --json Print the list in JSON format.
--help Show this message and exit.
viat tracked [OPTIONS]
Print out the tracked file paths.
Options:
-j, --json Print the list in JSON format.
--no-data Print only those paths without any recorded attributes.
--help Show this message and exit.
viat update [OPTIONS] PATH ATTRS
Merge the stored attributes for a tracked file with a new JSON object.
Options:
--help Show this message and exit.
ENVIRONMENT
VIAT_DIR
Use a concrete vault directory than searching through the current direc‐
tory upwards.
TUTORIAL
First, a vault must be initialized:
viat init
The vault is determined by a ".viat" subfolder that contains "config.toml" and
"storage.toml" files (JSON is also supported for both). We can immediately set
attributes for any file on the file system:
$ viat update tractatus.pdf '{"author": "Ludwig Wittgenstein", "year":
1921}'
Warning: File 'tractatus.pdf' is not being tracked.
{"author": "Ludwig Wittgenstein", "year": 1921}
All stored attributes for the file get printed; in this case the only stored at‐
tributes are those we have just added. We also get a warning saying that the
vault's tracker does not know about this file.
The role of the tracker is to enumerate the files that are explicitly tracked by
the vault. The default glob-based tracking provider requires explicit patterns.
We can track all PDF files in the root of the vault using the following configu‐
ration:
[tracker.glob]
patterns = ["*.pdf"]
With this, we can add new properties without warnings:
$ viat set tractatus.pdf rating 4
{"author": "Ludwig Wittgenstein", "year": 1921, "rating": 4}
The above worked because "true" is a valid JSON value; if we were to set a
string instead, we would have to escape it in quotes, which is inconvenient. In‐
stead, we can treat the value as a string by passing the "--raw" flag:
$ viat set --raw tractatus.pdf publisher 'Annalen der Naturphilosophie'
SCRIPTING
Tracking is useful for ensuring consistency with the file system, but also for
shell scripting. For example, the following command produces a table of vari‐
ables:
$ viat shell-export
path=tractatus.pdf publisher='Annalen der Naturphilosophie' rating=4 au‐
thor='Ludwig Wittgenstein' year=1921
This can be utilized in bash as follows:
viat shell-export | while read line; do
eval "export $line"
# The attributes are now exported as variables
done
In fish shell this is even simpler:
for line in (viat shell-export)
eval "export $line"
# The attributes are now exported as variables
end
If we add another file, "zarathustra.pdf", and if the tracker lists it after
"tractatus.pdf", then Viat would try to reset the missing attributes to avoid
reusing variables from the previous loop iteration:
$ viat shell-export
path=tractatus.pdf publisher='Annalen der Naturphilosophie' rating=4 au‐
thor='Ludwig Wittgenstein' year=1921
path=zarathustra.pdf publisher= rating= author= year=
SCHEMAS
It makes sense to utilize JSON schemas. Let us add the following to
".viat/schema.json":
{
"type":"object",
"properties": {
"year": {"type": "number"}
}
}
Now we can no longer set the year to anything that is not a number:
$ viat set tractatus.pdf --raw year string
Error: Validation error for 'tractatus.pdf': data.year must be number.
The essence of the tool is that the attributes are stored in plain text formats
that can be edited committed to version control. For example, ".viat/stor‐
age.toml" should now look as follows:
["tractatus.pdf"]
author = "Ludwig Wittgenstein"
year = 1921
rating = 4
publisher = "Annalen der Naturphilosophie"
If we manually change the year to "string", we will get a warning when loading
the vault:
$ viat get tractatus.pdf rating
Warning: Validation error in stored data for 'tractatus.pdf': data.year
must be number.
4
(RE)MOVING FILES
If we move "tractatus.pdf" to "book.pdf", viat will no longer know about it:
$ viat get book.pdf rating
Warning: File 'book.pdf' is not being tracked.
Error: Attribute 'rating' has not been set for 'book.pdf'.
Such discrepancies can be determined relatively easily:
$ viat stale
tractatus.pdf
$ viat tracked --no-data
book.pdf
For such cases, we provide the helpers "viat mv" and "viat rm", but otherwise
avoid being too clever.
0.10.3 2026-06-16 VIAT(1)