Browse the docs

File attribute

Passes when a file or folder attribute, such as its size, modification date, tags or extension, compares the way you ask.

attribute of path op value

Keyboard Maestro: File Attribute (Is, Contains, Is Before, Is After)

Details #

Reads one attribute of the file or folder at path and compares it with value using op. ~ in the path is expanded.

The attribute names are Keyboard Maestro's: FileType (File, Folder or Symlink), Size (bytes), CreationDate, ModificationDate, AddedDate, LastUsedDate, DownloadedDate, WhereFrom, OwnerName, OwnerID, GroupName, GroupID, POSIXPermissions (octal text such as 644), ExtensionHidden, Invisible, HFSCreatorCode, HFSTypeCode, ContentType (a type identifier), ContentKind (such as "PDF Document"), Tags (a list), Comment (the Finder comment), ParentPath, Name, BaseName, Extension and DisplayName. Four more serve Hazel's conditions: ColorLabel (none, gray, green, purple, blue, yellow, red or orange), Contents (the text of the file, from Spotlight or, for a file up to 2 MB, read directly), Depth (how many folders deep the file is under the folder named in root; 0 is directly inside it) and LastMatched (when Remember a file as handled last recorded the file under the key in state).

The operators: eq, ne, lt, gt, contains, startsWith, endsWith, matches (a regular expression), conformsTo (a ContentType that is, or is a kind of, the type you name: public.image holds for a PNG), and for dates before, after, inLast and notInLast (a length of time: 3 days, 2 weeks, 18 hours). Text comparisons with eq, ne, contains, startsWith and endsWith ignore case. For a date attribute, value can be seconds since 1970, an ISO 8601 date, 2026-10-24, 2026-10-24 09:30[:ss], or a phrase the system can read as a date; for dates, eq and ne allow one second of difference. With a list such as Tags, contains tests for one item.

The trace shows the path, the attribute and the actual value read. Reading a file is harmless, so it happens for real in a dry run too.

Every condition accepts "negate": true, which flips the verdict. The trace records what was compared before the flip, so a negated condition that blocks a macro still shows the real values.

Conditions in an Only if list combine with all: every one must pass, and an empty list always passes. An if step or a repeat loop takes a match of all (default) or any.

Parameters #

ParameterTypeRequiredValuesWhat it does
attributetextYesOne of the names listed above. Defaults to Name.
opone ofYeseq ne lt gt before after contains matches gte lte startsWith endsWith inLast notInLast conformsToOne of eq, ne, lt, gt, before, after, inLast, notInLast, contains, startsWith, endsWith, matches, conformsTo.
pathtextYesThe file or folder. ~ and {{ }} work.
roottextFor Depth: the folder the depth is counted from.
statetextFor LastMatched: the key file.remember used.
valueany valueWhat to compare with. Defaults to empty text.

Examples #

Is Applications a folder
Do
  1. If the file type of “Applications” is “Folder”
  2. Show “Applications is a folder”
  3. Else
  4. Show “Applications is not a folder”
Open in Switchboard to try it
Bigger than 1 MB
Do
  1. If the size of “true” is above 1000000
  2. Show “Larger than 1 MB”
  3. Else
  4. Show “1 MB or smaller”
Open in Switchboard to try it

Gotchas #

  • A missing file, or an attribute the file doesn't have (WhereFrom on a file you made), makes the condition fail rather than error, and the trace shows found: false. Negating it therefore passes. Test File exists first when that matters.

  • An unknown attribute fails with unknown file attribute "...". Names are case sensitive.

  • A date can only be compared with eq, ne, lt, gt, before, after, inLast and notInLast; anything else fails with a date can't be compared with "...".

  • Size is in bytes and lt and gt compare numbers, so 1000000 is one megabyte.

See also #