Using Obsidian

A Flint is plain Markdown, so it needs no editor. Obsidian is the editor that Flint supports. This guide shows how to open a Flint, how Flint keeps the Obsidian files of a Flint, and what to do when a command names a next step.

Flint installs one set of released files into .obsidian/ of each Flint. Flint calls this set the Obsidian payload. Obsidian in Other Commands lists the Obsidian output of the other commands.

Prerequisites

• Flint is installed on this machine.
• Obsidian is installed on this machine.
• You work inside a Flint, or you name one with -p <folder>.

The Model

Each Flint pins one release of the Obsidian payload in flint.json. Flint calls this release the pin. flint sync installs the pin. flint obsidian update moves the pin to a newer release.

Each file in .obsidian/ has one owner:

Flint verifies each release file by its hash. Flint copies the initial settings of a settings file once, only when the file is absent. After that, Flint never changes the file unless you ask or a named settings migration runs. Flint never writes a runtime file.

Flint saves each file that it replaces or removes, before the write. Flint never deletes a backup by itself. A backup stays on this machine.

Open a Flint

Open a Flint with Flint, not from inside Obsidian:

flint open "My Notes"             # a Flint by its name
flint open                        # the Flint of the working folder
flint open computer               # the Computer Flint of this machine, from any folder
flint open guide "NUU Cognition"  # a type and a name
flint open "My Notes" --no-launch # print the folder; open nothing

The word computer is reserved for the Computer Flint. When this machine has no Computer Flint, flint open computer refuses with This machine has no Computer Flint. and Next: flint setup computer.

When the vault is closed, flint open completes a waiting install first. Then it launches Obsidian and waits up to 15 seconds for the NUU Flint plugin of the vault. When the vault is open, it raises the window. In a terminal, a loading row names each wait while it runs: the payload install, the start of Obsidian, and the wait for the vault.

Obsidian opens a link only for a folder in its vault registry. So when Obsidian does not run, Flint first adds the Flint to the vault registry. When Obsidian runs and does not know the Flint yet, flint open opens nothing. It prints the one step: Obsidian: open "My Notes" once from Obsidian: Manage vaults, then Open folder as vault, then choose <path>. After that first open, flint open works for this Flint.

Trust

With the trust setting auto (the default), flint open trusts a Flint that passes the trust check, so Obsidian does not ask. The check passes when the payload is installed, the plugin files are the release files, and .obsidian/plugins holds no other plugin. Flint asks the NUU Flint plugin of an open vault to open your Flint with trust. The plugin sets the trust of Obsidian for the new vault before the vault loads. When no vault is open and your Flint passes the check, Flint starts Obsidian with the Computer Flint first and opens your Flint through it. So a second window can open. The result line names the Computer Flint: ✓ Obsidian: opened "My Notes" through the Computer Flint "Ada Laptop".

Obsidian still asks once ("Trust author and enable plugins") in these cases:

• the first open of the Computer Flint on this machine. flint setup does this open at its step 7. See Setting Up a Machine > Step 7: Open and Onboarding and The Computer Flint.
• the trust setting is ask.
• the check fails, for example because a plugin file changed. flint open then names the reason.
• no vault is open, and this machine has no Computer Flint.
• you open the vault from Obsidian itself, not with flint open.

When the first open of the Computer Flint shows "Vault not found", choose Open folder as vault in Obsidian. Select the folder of the Computer Flint. Then click Trust author and enable plugins.

After the click, the plugin reloads Obsidian one time. An automatic trust needs no reload.

When a Flint is already open without its plugins, flint open trusts it, but the plugins start only after a reload of that window. flint open then prints Obsidian: "My Notes" is open, and its plugins did not start. Reload its window to start them.

Restricted Mode. The plugin never changes a vault that you put in Restricted Mode. flint open then prints Obsidian: launch requested. "My Notes" is in Restricted Mode: turn on community plugins in Settings, Community plugins. The button Browse vault in Restricted Mode on the trust screen is for one load only: Obsidian stores nothing, and it asks again at the next load. With auto, the next flint open then trusts the Flint. To keep a Flint in Restricted Mode, open Settings → Community plugins, and click Turn on next to Restricted mode.

To let Obsidian ask for each new vault instead, set the trust setting to ask:

flint config set obsidian-trust ask
flint config set obsidian-trust auto

flint config get obsidian-trust prints the setting. flint obsidian status shows the setting and the check on the line Trust.

Trust lets the code of the plugins run. Code in your notes (a DataviewJS block, a Templater startup script) also runs in a trusted vault, as it does after the click. Use ask on a machine where you open Flints from people that you do not trust.

Check the State

Look at the state first. flint obsidian status writes nothing:

flint obsidian status

Obsidian payload
  Pinned     : 0.7.0 (108feb3)
  Installed  : 0.7.0 · 63 release files verified
  Applied    : 1 key (release 1 · machine 0 · Flint 0)
Vault
  Obsidian   : closed
  Trust      : auto (flint open trusts this Flint)

Next: nothing to do.

The last line is the one next command. Use --check to also probe each Obsidian manager of this machine for an old plugin. It exits 2 when an error or a warning is present. Use --tinderbox for one row per member of a Tinderbox. Use --json for the status as JSON.

Sync and Update

flint sync installs the pinned release. It never moves the pin. The pin is a fact of the Flint, and Git shares it. Only flint obsidian update moves the pin.

When flint sync finds the vault open, it records a pending install and exits 0. This is a normal state, not a failure. The plugin shows a notice in the vault. To complete the install, close the vault in Obsidian. Then open it with Flint:

flint open "My Notes"

flint obsidian update pins the recommended release and installs it in one step. It writes the pin last. It keeps every settings file. After an update, commit flint.json, for example with flint git sync. Each other machine installs the new pin at its next flint sync.

flint obsidian update --dry-run     # print the plan; write nothing
flint obsidian update               # pin the recommendation and install it

flint obsidian update needs a closed vault. On an open vault, it refuses with exit 2 and writes nothing. To see the plan as text, run flint obsidian update --dry-run.

A Changed Release File

A changed release file is a release file that something changed outside Flint. Do not edit the release files in .obsidian/. An install stops before the first write and lists each changed path:

Blocked: 1 release file changed outside Flint.
    plugins/terminal/main.js
  No files were changed.

Look at the plan first. Then replace the file. The replace saves your version in a backup first:

flint obsidian repair --replace --dry-run
flint obsidian repair --replace

A missing release file is not a change. flint sync installs it again.

Repair

flint obsidian repair restores the release files of the pinned release. It installs each missing release file again.

Run each form with --dry-run first.

Repair works on an open vault. When a live plugin can reload the vault, repair writes the files and then reloads Obsidian. When a terminal tab runs a process, repair refuses before any write and names each such tab. Then run the same command with --yes. When no live plugin answers, repair refuses and names the close step.

flint obsidian reset, flint obsidian push, and flint obsidian patches are removed. Each prints the new command.

Backups and Restore

List the backups, newest first:

flint obsidian backups list
flint obsidian backups show <id>

A restore has three forms:

To delete old backups, look at the preview first:

flint obsidian backups prune --keep 5            # the preview: each backup to delete, and the size
flint obsidian backups prune --keep 5 --yes      # delete them

Prune always keeps the newest backup of each scope. Use --scope flint|registry|deleted|all to select a scope. Use --older-than 4w to delete by age.

Applied Settings

Applied settings are keys of appearance.json and app.json that the NUU Flint plugin applies each time it loads. Use an applied setting for a value that must stay the same, for example one theme for every Flint on your machine. To change one, use flint obsidian applied set, not an edit of the settings file. When you change an applied key in Obsidian, your change holds until the next load of the plugin. Then the declared value comes back.

Applied settings have three layers. A later layer wins:

The allowed keys of appearance are cssTheme, theme, translucency, enabledCssSnippets, showRibbon, accentColor, baseFontSize, interfaceFontFamily, textFontFamily, and monospaceFontFamily. The allowed keys of app are editor and file keys, for example showLineNumber, vimMode, readableLineLength, tabSize, and userIgnoreFilters. Flint refuses a key that is not in the list.

flint obsidian applied                                          # each key: the value, the layer, and the last result
flint obsidian applied set appearance.cssTheme Baseline         # the Flint layer (flint.toml)
flint obsidian applied set appearance.cssTheme "Tokyo Night" --machine
flint obsidian applied set appearance.enabledCssSnippets --add blockquote-tables
flint obsidian applied unset appearance.cssTheme
flint obsidian applied apply                                    # send the set to the open vault now

• set takes a value, or --add and --remove for a list key. It reads the value as JSON when it can (true, 16), else as text.
• unset removes the key from its layer. Obsidian keeps the last value until you change it in Obsidian.
• apply sends the resolved set to the open vault at once. No reload is necessary. On a closed vault, it waits for the next open.

Appearance Profiles

An appearance profile is a set of appearance keys that you activate and deactivate as one unit. List the profiles of the installed release first. One profile ships with the release: baseline-transparent. It sets the Baseline theme, window translucency, and one snippet. It is macOS only for now.

flint obsidian profiles list
flint obsidian profiles activate baseline-transparent
flint obsidian profiles deactivate
flint obsidian profiles                # choose in a terminal; choose the active entry to deactivate it

On an open vault, the plugin sets the keys at once. No reload is necessary. On a closed vault, Flint writes appearance.json after a backup. Deactivation restores only the keys that you did not change since the activation. It keeps your later changes and names them.

An appearance profile cannot set a key that an applied setting holds. The activation then refuses as a whole and names the key. In the same way, flint obsidian applied set refuses a key that the active profile holds. Deactivate the profile first.

Reload and Terminal Tabs

A reload of Obsidian restarts its window and stops every terminal tab. So no Flint command reloads Obsidian by itself, except flint obsidian repair on an open vault. To reload, ask for it:

flint obsidian reload

When a tab runs a process, reload refuses and lists the tabs. Then run the same command with --yes.

To open a terminal tab in Obsidian and start an agent session in it, use flint obshn:

flint obshn <orbh-profile> [prompt]

It takes -p <flint> for another Flint, --at <scope> for the session store, and --account <name> for the harness account.

The Vault Registry

Obsidian keeps a registry of vaults on this machine. Flint moves the registry entry when a Flint command moves or renames a Flint, so the trust stays with the vault. When Obsidian runs during the move, the registry change waits until Obsidian stops. With the trust setting auto, the next flint open of the new path trusts the vault again. When entries point at missing folders, clean them. Quit Obsidian first. Then run the preview, then the write:

flint obsidian vaults repair
flint obsidian vaults repair --yes

It never removes an entry on a volume that is not mounted.

Turn Obsidian Off on This Machine

A server, or a machine with no Obsidian, can turn the Obsidian layer off:

flint config set obsidian off
flint config get obsidian          # prints on or off
flint config set obsidian on

With the choice off, an explicit Obsidian command refuses and names the on command. flint create, flint sync, and the move, delete, and Tinderbox commands skip Obsidian and print one row. Reads such as flint obsidian status still work. To skip Obsidian for one run only, use flint create "<name>" --no-obsidian. It never writes the config. See Global Configuration.

Flint supports Obsidian on macOS and Linux only. On another platform, each Obsidian command prints ✘ Flint supports Obsidian on macOS and Linux only. Flint 0.7.0 does not support Obsidian from Flatpak or Snap. Install the AppImage or the native package of Obsidian, or turn Obsidian off. In these cases, flint create skips Obsidian, as with the choice off. Obsidian in Other Commands shows the output.

Upgrading from 0.6.x

In a Flint of 0.6.x, .obsidian/ is a Git clone of the payload source. Flint 0.7.0 changes it into a plain install of the pinned release. Each machine runs this conversion once for each Flint. Until the conversion, flint sync stops and names the conversion command.

For each Flint, close its vault in Obsidian. Then look at the plan, then run it:

flint migrate run --dry-run
flint migrate run

The step keeps every settings file, every runtime file, and the vault registry entry. It saves each replaced file in one backup. When the step wrote the pin, commit flint.json. Then open the Flint with flint open "<name>".

flint obsidian update and flint obsidian repair convert a legacy payload too. flint migrate run, flint sync, and flint obsidian repair can convert an open vault when its NUU Flint plugin runs: they reload the vault after the write. flint obsidian update needs a closed vault. When Flint cannot reload the open vault, or the fetch fails, the conversion waits. Close the vault, then run flint open "<name>" or flint sync.

Troubleshooting

More cases are in Troubleshooting.

Next Steps

• Creating a Flint
• Using Tinderbox
• Global Configuration
• CLI Commands
• Obsidian in Other Commands
• Configuration
• Troubleshooting