Phials documentation
Developer docs
AI Notice: Most documentation right now was auto-generated by an LLM. Handwritten documentation will be implemented over time on the road to 1.0

Create and manage a Vial

Turning a folder into a Vial adds a small hidden .phials folder beside your files and unlocks properties, notes, saved views, relations, and more, without changing the files themselves.

Prerequisites

You need a normal folder you can write to (for example a project or inbox). For background on what a Vial is, see Vials overview.

Create a Vial from a folder

  1. In the file list, right-click a folder that is not already a Vial and choose Create Vial. (That command is only shown for folders that do not yet have a Vial.)
  2. In the Create Vial dialog, choose the folder (if needed) and review Name. It defaults to the folder name and is the display name for this Vial.
  3. Click Create. While the name field is focused, Enter also submits the form.

After creation, browsing inside that folder shows vial controls in the View & arrange strip above the file list: the vial name menu, saved view pills, and Vial options (…) for properties and configuration.

If the folder already had saved views as a normal folder, those are kept automatically. They move into the Vial so they travel with it (same names and order). See Saved views in a Vial.

Where the metadata lives

Phials creates a hidden **.phials/** folder inside the Vial root. It holds a small SQLite database, notes, and schema data. You usually do not open it by hand; if you move or copy the whole folder, the metadata moves with it.

Vial controls in the explorer strip

When the active pane is browsing inside a Vial, the view/arrange strip (under the path bar) includes:

  • Vial name (left): opens a menu with Edit vial…, Open in file explorer, Copy path, and Remove from Vials - the same actions as a navigator vial context menu except Open.
  • Saved views as pills. See Saved views.
  • Save view settings and Reset view on the right when a saved view is active.
  • View mode, Filter, sort & group, and Field visibility on the right.
  • Vial options (… menu): Add Property, Configure properties, and related vial settings. See Properties.

Known Vials and the Vials list module

Every time you open a Vial, Phials records it as a Known Vial (with a last-opened time). That registry powers the sidebar Vials module and helps resolve relation links across locations.

Add the Vials panel to the sidebar and dock it where you like (see Arranging Panels). It lists Known Vials as a tree. Expand a Vial to browse indexed folders and files. Selecting a file either opens its fullscreen preview (when the file type has one), or navigates to its parent folder and selects the file in the list. If a file already has a per-file note, a Note button appears on its row and opens that note.

If you have not opened any Vials yet, the module shows No known Vials. Create a Vial and open it once to populate the list.

To drop a Vial from Known Vials without deleting data, use Remove from Vials where that command appears (for example in a context menu on a Known Vial in the navigator). That only removes the shortcut; your .phials/ folder is unchanged. You can also ignore Known Vials and manage the folder purely from the file tree.

Remove or move a Vial

  • Move or rename the folder on disk: the Vial and its metadata move with it. Relation links use a stable vial ID inside .phials/, so they keep working across renames when Phials can find the folder.
  • Un-vial a folder by deleting the **.phials/directory inside it.Warning:** that permanently removes properties, notes, saved views, and other Vial data for that folder. Phials cannot undo that from inside the app.

Tips

  • Create Vial is hidden once a folder already is a Vial.
  • The vial controls in the View & arrange strip appear only when the active file-list pane is inside a Vial root or its subfolders.
  • Each Vial has a stable ID so relations and references can survive folder moves and renames.
  • Known Vials are a convenience list; removing one from the list does not delete .phials/.