Nib reads project settings from the [tool.nib] section of pyproject.toml. This lets you define build defaults so that nib run and nib build work without any flags.

Sections overview¶

[tool.nib]¶

Top-level project settings.

[tool.nib]
entry = "src/main.py"

[tool.nib.build]¶

Build configuration. All keys are optional -- sensible defaults are used when omitted.

[tool.nib.build]
name = "Weather Widget"
identifier = "com.example.weatherwidget"
version = "2.1.0"
icon = "src/assets/icon.png"
min_macos = "14.0"
extra_deps = ["requests", "pillow"]
launch_at_login = true

[tool.nib.build.plist]¶

Controls values written to the app's Info.plist. These affect how macOS treats your application.

[tool.nib.build.plist]
copyright = "Copyright 2025 Your Name"
category = "public.app-category.utilities"
notification_style = "banner"
dock_icon = false
build_number = "42"
url_schemes = ["myapp"]

allow_http¶

By default, macOS enforces App Transport Security (HTTPS only). You can relax this globally or per-domain:

# Allow HTTP to all domains
allow_http = true

# Allow HTTP to specific domains only
allow_http = ["api.example.com", "cdn.example.com"]

Document type associations¶

Register your app as a handler for specific file types using TOML array-of-tables syntax.

[[tool.nib.build.plist.document_types]]
name = "Text Document"
extensions = ["txt", "md"]
role = "Viewer"

[[tool.nib.build.plist.document_types]]
name = "JSON File"
extensions = ["json"]
role = "Editor"

[tool.nib.build.plist.usage]¶

Privacy permission descriptions. macOS requires a usage string for each protected resource your app accesses. If the user's code references Permission.CAMERA or Permission.MICROPHONE, Nib auto-detects them with generic descriptions -- but you should provide your own.

[tool.nib.build.plist.usage]
camera = "This app uses the camera for video preview."
microphone = "This app uses the microphone for voice commands."
location = "This app uses your location to show local weather."

[tool.nib.build.plist.custom]¶

An escape hatch for arbitrary Info.plist keys. Values in this section are merged last and can override anything set by other options.

[tool.nib.build.plist.custom]
NSSupportsAutomaticTermination = true
NSSupportsSuddenTermination = true
MyCustomKey = "custom value"

Complete example¶

A fully annotated pyproject.toml with all available options:

[project]
name = "weather-widget"
version = "2.1.0"
description = "A macOS menu bar weather app"
requires-python = ">=3.10"
dependencies = [
    "requests",
    "pillow",
]

[tool.nib]
# Entry point script -- used by `nib run` and `nib build`
entry = "src/main.py"

[tool.nib.build]
# App display name
name = "Weather Widget"

# Bundle identifier
identifier = "com.example.weatherwidget"

# App version (overrides [project].version for the bundle)
version = "2.1.0"

# Icon file (.icns or .png -- PNG is auto-converted)
icon = "src/assets/icon.png"

# Minimum macOS version
min_macos = "14.0"

# Packages to exclude from bundling
exclude = []

# Additional dependencies if auto-detection misses them
extra_deps = []

# Start at login (requires signed app)
launch_at_login = false

[tool.nib.build.plist]
copyright = "Copyright 2025 Jane Developer"
category = "public.app-category.weather"
notification_style = "banner"
dock_icon = false
background_only = false
build_number = "42"
allow_http = ["api.weather.com"]
url_schemes = ["weather-widget"]

# File type associations
[[tool.nib.build.plist.document_types]]
name = "Weather Data"
extensions = ["weather", "json"]
role = "Viewer"

# Privacy descriptions
[tool.nib.build.plist.usage]
location = "Weather Widget uses your location to show local forecasts."
camera = "Weather Widget uses the camera for sky condition detection."

# Custom plist keys (escape hatch)
[tool.nib.build.plist.custom]
NSSupportsAutomaticTermination = true