Directories

Directories are logical name-to-path mappings. Instead of hard-coding a path like outputs/renders everywhere, you give it a name (outputs) and use that name in macros. If you later change where outputs should go, you update the directory definition in one place.

Default directories

The system defaults define four directories:

Name	Default path	Description
inputs	inputs	Files brought into the project (uploaded, copied, downloaded)
outputs	outputs	Files generated by nodes
temp	temp	Temporary working files
previews	.griptape-nodes-previews	Preview thumbnails (hidden folder)

All default paths are relative and resolve against the project base directory.

Using directory names in macros

Directory names are available as variables in any macro. When a macro is resolved, the project system automatically substitutes the directory name with its configured path:

Template:  {outputs}/{file_name_base}.{file_extension}
           ↓
Resolved:  outputs/my_image.png

You do not supply directory values yourself — they come from the directory definitions. Directory names are reserved: if you try to pass a variable with the same name as a directory, the system will reject it with an error to prevent ambiguity.

Customizing directory paths

Override a directory's path in your griptape-nodes-project.yml:

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  outputs:
    path_macro: "renders/final"

Now {outputs} in any macro resolves to renders/final instead of outputs.

Adding new directories

Add a directory that doesn't exist in the defaults:

directories:
  deliverables:
    path_macro: "client_deliverables"

Once added, {deliverables} is available in any macro.

Directory paths with macros

The path_macro field supports tilde (~) expansion, macro syntax, and environment variable references:

directories:
  downloads:
    path_macro: "~/Downloads"

This maps the downloads directory to the current user's Downloads folder, regardless of the machine it runs on.

directories:
  outputs:
    path_macro: "$OUTPUT_BASE/renders"

If $OUTPUT_BASE is set in your environment (or in the project's environment section), it will be substituted when the path is resolved.

You can also reference builtin variables in directory paths:

directories:
  outputs:
    path_macro: "{workflow_dir}/renders"

This makes the outputs directory relative to the current workflow's location rather than the project base directory.

Reserved names

Directory names are reserved across the entire variable namespace. You cannot use a directory name as a user-supplied variable in a macro call — the system will return an error if you try. This protects against accidentally overriding a directory path through a variable name collision.

The builtin variables (project_dir, workspace_dir, workflow_name, workflow_dir, static_files_dir) are also reserved and cannot be overridden. See Environment & Builtin Variables.