How Rules Work - tooka-org/tooka GitHub Wiki

Rules are the backbone of Tooka — they tell Tooka which files to match and what actions to take. Everything you do with Tooka revolves around defining and executing rules.

🧠 Rules

Rules are written in YAML, and once submitted to the CLI, Tooka stores them in a centralized rules.yaml file. The location of this file is set in your configuration.

You can submit:

A single rule
A file containing multiple rules

The CLI checks for basic validity at submission time, but logical correctness is up to you — that's why dry-runs are important!

➕ Adding Rules

To add a rule to Tooka:

tooka add <file.yaml>

🧱 Rule Structure

Here's a basic example of a rule file:

id: example_rule
name: "Example Rule"
enabled: true
description: "Describe what this rule does"
priority: 1

when:
  any: false
  filename: "^.*\\.jpg$"
  extensions: ["jpg", "jpeg"]
  path: "**/holiday/**"
  size_kb:
    min: 10
    max: 5000
  mime_type: "image/jpeg"
  created_date:
    from: null
    to: null
  modified_date: null
  is_symlink: false
  metadata:
    - key: "EXIF:DateTime"
      value: null

then:
  - type: move
    to: "/path/to/destination"
    preserve_structure: false
  - type: rename
    to: "{{metadata.EXIF:DateTime|date:%Y-%m-%d}}-{{filename}}"

🔍 `when`: Match Conditions

These conditions determine which files the rule applies to. By default, conditions are combined using AND logic — all must be true. Set any: true to use OR logic.

Field	Type	Description
`any`	boolean	Use `true` for OR logic between conditions
`filename`	string (regex)	Match the file name using a regular expression
`extensions`	list of strings	Match file extensions (without the dot)
`path`	string (glob)	Match file paths using glob patterns
`size_kb`	object	File size in kilobytes, with `min` and/or `max`
`mime_type`	string	Match based on MIME type (e.g. `image/jpeg`)
`created_date`	object	ISO 8601 date range: `from`, `to`
`modified_date`	object or null	Same as above, but for last modification date
`is_symlink`	boolean or null	Match symlinks (`true` or `false`)
`metadata`	list of objects	Match metadata (e.g., EXIF tags like `DateTime`)

⚙️ `then`: Actions

These define what to do when a file matches the rule.

Action Type	Fields
`move`	`to` (path), `preserve_structure` (bool)
`copy`	`to` (path), `preserve_structure` (bool)
`delete`	`trash` (bool) — delete or move to trash
`rename`	`to` (template string, e.g. `{{filename}}`)
`execute`	`command` (string), `args` (list)
`skip`	(no fields) — skips further rules for the current file

Tip

Use the rename template syntax to dynamically rename files using metadata, dates, or file attributes.

🧪 Safe Testing with Docker

Want to try Tooka in a clean environment? We provide a Dockerfile that installs the latest release. You can safely test your rules and files in a sandbox.

🔨 Build the Image

docker build -t tooka-playground .

🧑‍💻 Start a Shell with Tooka

docker run --rm -it tooka-playground

Inside the container:

tooka --help
tooka config
tooka template

🗂️ Mount Your Files and Rules

docker run --rm -it \
  -v "$HOME/Downloads:/input" \
  -v "$PWD/rules:/rules" \
  tooka-playground

Note

Use /input for test files and /rules for your rule files. Perfect for experimenting, debugging, or submitting reproducible bug reports.