### Clone, install, and build the FileClass CLI

Source: https://mdelobelle.github.io/fileclass/cli

Clones the fileclass-cli repository, installs dependencies, and builds the project. Run these commands from a terminal after cloning.

```bash
git clone https://github.com/mdelobelle/fileclass-cli
cd fileclass-cli
npm install
npm run build

```

--------------------------------

### Set a user-owned npm prefix for npm link

Source: https://mdelobelle.github.io/fileclass/cli

Configures npm to install global packages into ~/.npm-global, avoiding sudo. After this, run npm link and add the bin directory to PATH.

```bash
npm config set prefix ~/.npm-global
```

--------------------------------

### FileClass CLI command reference

Source: https://mdelobelle.github.io/fileclass/cli

Lists the main CLI commands: tui, fileclasses, schema, explain, list, get, set, validate, and set-where. The validate command exits with code 1 on violations, and set-where is a dry run unless --apply is used.

```bash
fileclass tui                              # interactive browse + edit (TUI)
fileclass fileclasses                      # every fileClass
fileclass schema Book                      # a fileClass's options + fields
fileclass explain "Books/Dune.md"          # a note's fileClasses + resolved fields
fileclass list Book --columns title,author --where "status is unread" --limit 20
fileclass get "Books/Dune.md" status
fileclass set "Books/Dune.md" status read  # validated single write

# data quality (exit code 1 if any violation — CI-friendly)
fileclass validate --fileclass Book

# bulk edit (dry-run unless --apply)
fileclass set-where Book status "to read" --where "status isEmpty" --apply
```

--------------------------------

### Run the CLI directly

Source: https://mdelobelle.github.io/fileclass/cli

Runs the CLI without installing it globally by invoking the built script directly with a command.

```bash
node dist/cli.js <command>
```

--------------------------------

### explain(path)

Source: https://mdelobelle.github.io/fileclass/cli

Returns a note's fileClasses, ancestry, and resolved field values.

```APIDOC
## explain

### Description
Returns a note's fileClasses, ancestry, and resolved field values.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.explain(path)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the note

### Response
#### Success Response
- **fileClasses** (array) - The fileClasses applied to the note
- **ancestry** (array) - The ancestry of the note
- **field values** (object) - Resolved field values

#### Response Example
```json
{
  "fileClasses": ["Book"],
  "ancestry": ["Book"],
  "fields": {
    "author": "John Doe"
  }
}
```
```

--------------------------------

### Duration field storage format

Source: https://mdelobelle.github.io/fileclass/fields

Example of how duration values are stored as RFC 5545 strings in a note's properties.

```yaml
prep_time: PT1H30M   # 1 h 30 min
total_time: P1DT6H   # 1 day 6 h
brew: P2W            # 2 weeks
```

--------------------------------

### Multi-line YAML block scalar

Source: https://mdelobelle.github.io/fileclass/fields

Example of how a Multi-line input field value is stored as a YAML block scalar when it contains line breaks.

```yaml
overview: |-
  First line.
  Second line, after a real break.  

```

--------------------------------

### Configure class destinations in newNotes

Source: https://mdelobelle.github.io/fileclass/schema

Configure multiple destinations for a class's new notes. Each destination has a name, folder, and template. Edit these in the class's Options → New notes; the folder and template are never touched by removal.

```yaml
newNotes:
  - name: Professional
    folder: 1_People/Contacts
    template: Templates/Person pro.md
  - name: Artist
    folder: 2_Artists
    template: Templates/Person artist.md

```

--------------------------------

### Access ObjectList properties via formulas

Source: https://mdelobelle.github.io/fileclass/fields

Demonstrates how to count list items, access specific indices, and notes that mapping functions are not supported in formulas.

```yaml
formulas:
  Count: note.editions.length            # 3 · 2 · empty where the key is absent
  FirstFormat: note.editions[0].format   # indexing works, and reaches a child
  FirstYear: note.editions[0].year
  # Formats: note.editions.map(e => e.format).join(", ")   ← renders nothing
```

--------------------------------

### openSchema(fileClass)

Source: https://mdelobelle.github.io/fileclass/cli

Opens the schema editor in the Obsidian window.

```APIDOC
## openSchema

### Description
Opens the schema editor in the Obsidian window.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.openSchema(fileClass)`

### Parameters
#### Path Parameters
- **fileClass** (string) - Required - The name of the fileClass

### Response
#### Success Response
- **ok** (boolean) - Whether the operation succeeded
- **message** (string) - Status message

#### Response Example
```json
{"ok": true, "message": "Schema editor opened"}
```
```

--------------------------------

### listFileClasses()

Source: https://mdelobelle.github.io/fileclass/cli

Returns every fileClass with its extends, field count, icon, and whether it has a base.

```APIDOC
## listFileClasses

### Description
Returns every fileClass with its extends, field count, icon, and whether it has a base.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.listFileClasses()`

### Parameters
None

### Response
#### Success Response
- **fileClasses** (array) - List of fileClass objects, each containing:
  - **extends** (string) - The parent fileClass, if any
  - **field count** (number) - Number of fields
  - **icon** (string) - Icon identifier
  - **hasBase** (boolean) - Whether the fileClass has a base

#### Response Example
```json
[
  {
    "name": "Book",
    "extends": null,
    "fieldCount": 5,
    "icon": "book",
    "hasBase": false
  }
]
```
```

--------------------------------

### fileClass note frontmatter with fields and options

Source: https://mdelobelle.github.io/fileclass/schema

Defines a fileClass note in Metadata Menu's format. The frontmatter declares optional inheritance (extends), excluded inherited fields (excludes), tag and folder bindings (mapWithTag, tagNames, filesPaths), related views, a limit, an icon, a version, and a fields list with type and options. The path field uses "" for the root and parent ids joined by "____" for nesting.

```yaml
---
extends: Media          # optional parent fileClass
excludes: [draft]       # inherited field names to drop
mapWithTag: true        # bind notes tagged #Book to this fileClass
tagNames: [novel]       # extra tags that bind to this fileClass
filesPaths: [Library]   # bind notes under these folders
relatedViews:           # the views that list this class for one of *their* notes
  - field: author
    view: Books.base#A's Bs
limit: 20
icon: book
version: "2.0"
fields:
  - name: author
    id: a1b2c3
    type: Select
    options: [unknown, me]
    path: ""            # "" = root; nesting uses parent ids joined by "____"
---

```

--------------------------------

### Symlink fileclass into a bin directory

Source: https://mdelobelle.github.io/fileclass/cli

Creates a symlink from the built CLI script to ~/.local/bin/fileclass, making the command available on PATH.

```bash
ln -sf "$(pwd)/dist/cli.js" ~/.local/bin/fileclass
```

--------------------------------

### getFields(path)

Source: https://mdelobelle.github.io/fileclass/cli

Returns the fields on a note.

```APIDOC
## getFields

### Description
Returns the fields on a note.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.getFields(path)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the note

### Response
#### Success Response
- **fields** (object) - The fields and their values on the note

#### Response Example
```json
{
  "author": "John Doe",
  "pages": 123
}
```
```

--------------------------------

### Vault selection precedence

Source: https://mdelobelle.github.io/fileclass/cli

Shows the precedence order for choosing the target vault: --vault flag, FILECLASS_VAULT environment variable, fileclass use default, then active vault.

```text
--vault <name>   >   FILECLASS_VAULT (env)   >   `fileclass use` default   >   active vault
```

--------------------------------

### listNotes(fileClass, { columns?, where?, limit? })

Source: https://mdelobelle.github.io/fileclass/cli

Returns rows for a fileClass, with optional columns, where filter, and limit.

```APIDOC
## listNotes

### Description
Returns rows for a fileClass, with optional columns, where filter, and limit.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.listNotes(fileClass, { columns?, where?, limit? })`

### Parameters
#### Path Parameters
- **fileClass** (string) - Required - The name of the fileClass

#### Query Parameters
- **columns** (array) - Optional - List of column names to include
- **where** (string) - Optional - Filter condition
- **limit** (number) - Optional - Maximum number of rows

### Response
#### Success Response
- **rows** (array) - List of row objects

#### Response Example
```json
[
  {"title": "Book A", "author": "John"}
]
```
```

--------------------------------

### baseTable(fileClass)

Source: https://mdelobelle.github.io/fileclass/cli

Returns the fileClass's base view as columns/rows.

```APIDOC
## baseTable

### Description
Returns the fileClass's base view as columns/rows.

### Method
API method

### Endpoint
`app.plugins.plugins.fileclass.api.baseTable(fileClass)`

### Parameters
#### Path Parameters
- **fileClass** (string) - Required - The name of the fileClass

### Response
#### Success Response
- **columns** (array) - Column definitions
- **rows** (array) - Row data

#### Response Example
```json
{
  "columns": ["title", "author"],
  "rows": [
    {"title": "Book A", "author": "John"}
  ]
}
```
```