Phials documentation
Developer docs

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 the Vial toolbar above the file list: the Vial name, saved view pills, a + button to add properties, and a gear menu for 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:

  • Saved views as pills. See Saved views.
  • + (Add property) to define new columns. See Properties.
  • Vial settings (gear menu):
    • Configure properties opens the schema editor (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 toolbar appears 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/.