timectl 0.1.0

CLI to inspect and set file timestamps (atime, mtime, btime, and best-effort ctime).

timectl

Command-line tool to inspect and adjust file and directory timestamps (atime, mtime, btime, and best-effort ctime).

Testing: This project has only been tested on macOS 26. Behavior on other operating systems or versions is not guaranteed.

Requirements

• Python 3.10 (see pyproject.toml)

Install

Recommended: add the CLI from PyPI with uv’s tool installer (see Using tools):

uv tool install timectl
timectl --help

To run a one-off command without installing the tool globally, use uvx (alias for uv tool run):

uvx timectl --help
uvx timectl inspect .

You can also install from PyPI with pip:

pip install timectl
timectl --help

To work on this repository from a clone, use uv sync and uv run timectl ….

Commands

inspect

Show atime, mtime, ctime, and btime (when available) for a single path. Times are printed in the system local timezone.

timectl inspect              # default: current directory
timectl inspect path/to/file

set

Update timestamps for one root path (default: current directory). By default, directories are processed recursively (all entries under the tree).

timectl set [path] [--time <value>] [--fields <letters>] [--no-recursive]

Option	Description
--time	Target time; default is now. See Time formats.
--fields	Which fields to change: a (atime), m (mtime), c (ctime), b (btime). Default: amcb.
--no-recursive	Do not walk into subdirectories when path is a directory.

Field notes:

• a / m: Set via os.utime to the value of --time.
• b: On macOS, the tool tries Apple’s SetFile (from Xcode Command Line Tools) when available; otherwise b may be skipped with a reason in the output.
• c: The system does not allow setting ctime to an arbitrary value. With c in --fields, the tool refreshes ctime to the current moment after other updates. Therefore c is only allowed when --time is now (including the default). If --time is anything else and c is included (including the default amcb), the command exits with an error—use e.g. --fields amb to omit c.

Time formats

• now
• ISO 8601 (e.g. 2026-03-30T12:34:56+08:00)
• YYYY-MM-DD HH:MM:SS (interpreted in the local timezone if no offset is given)
• Unix seconds: @1711767296
• Nanoseconds: @1711767296000000000ns

Examples

# Inspect a file
timectl inspect ./README.md

# Set everything to now under current directory (default path, --time, --fields)
timectl set

# Set everything to now under a given root
timectl set ./some/dir

# Set atime/mtime/btime to a fixed time (omit c)
timectl set ./file.txt --time "2026-03-30 22:00:00" --fields amb

# Only touch the directory itself, not children
timectl set ./folder --no-recursive --time now

Limitations

• ctime cannot be set to a specific historical time; only a “touch to now” style refresh is supported, and only when --time is now.
• btime support depends on the platform and tools (on macOS, SetFile is used when present).
• Cross-platform and cross-filesystem timestamp semantics differ; this tool does not promise identical results outside the tested environment.

License

This project is licensed under the MIT License.