--- title: Properties and Resources description: Manage property definitions, note values, raw metadata, Views, Note Types, and Themes. --- ## Property Definitions Property definitions are shared with the desktop app through SQLite when available and mirrored to `.octarine/properties.json` for portability. Supported types are `string`, `text`, `tag`, `number`, `integer`, `float`, `boolean`, `bool`, `checkbox`, `list`, `array`, `tags`, `date`, `datetime`, `date-time`, `external_files`, and `tasks`. Names beginning with `oct.` are reserved. ### `property definitions list` List all definitions. ```bash octarine property definitions list octarine property definitions list --json ``` ```text # Default table output ╭────────┬────────╮ │ name ┆ type │ ╞════════╪════════╡ │ status ┆ string │ │ due ┆ date │ ╰────────┴────────╯ # JSON output {"schemaVersion":1,"ok":true,"data":[{"name":"status","type":"string"},{"name":"due","type":"date"}],"meta":{"truncated":false}} ``` ### `property definitions show` Show one definition by its exact name. ```bash octarine property definitions show status ``` ```text ╭───────┬────────╮ │ Field ┆ Value │ ╞═══════╪════════╡ │ name ┆ status │ │ type ┆ string │ ╰───────┴────────╯ ``` ### `property definitions define` Create a definition with a supported type. ```bash octarine property definitions define status --type string octarine property definitions define due --type date ``` ```text ╭───────┬────────╮ │ Field ┆ Value │ ╞═══════╪════════╡ │ name ┆ status │ │ type ┆ string │ ╰───────┴────────╯ ``` Names are case-insensitively unique. ### `property definitions delete` Delete a definition. Existing frontmatter values are not removed from notes. ```bash octarine property definitions delete legacy-status ``` ```text ╭─────────┬───────────────╮ │ Field ┆ Value │ ╞═════════╪═══════════════╡ │ deleted ┆ legacy-status │ ╰─────────┴───────────────╯ ``` ### `property definitions validate` Validate every definition for required fields, supported types, duplicates, and reserved names. ```bash octarine property definitions validate ``` ```text ╭─────────┬───────╮ │ Field ┆ Value │ ╞═════════╪═══════╡ │ checked ┆ 2 │ │ valid ┆ true │ ╰─────────┴───────╯ ``` ### `property definitions put` Replace the complete definition array from JSON or YAML. Use `--file -` for standard input. ```bash octarine property definitions put --file properties.json cat properties.yaml | octarine property definitions put --file - ``` ```text ╭────────┬────────╮ │ name ┆ type │ ╞════════╪════════╡ │ status ┆ string │ │ due ┆ date │ ╰────────┴────────╯ ``` The command validates the entire array before writing it. ## Note Property Values Values are stored in each note's YAML frontmatter. A matching definition controls validation where applicable. ### `property list` List every parsed property on a note. Values are returned as strings; a value written over several lines, such as a block list of tags, is returned in YAML flow style, like `[project, launch]`. ```bash octarine property list Projects/Launch.md ``` ```text ╭────────┬───────────────────╮ │ Field ┆ Value │ ╞════════╪═══════════════════╡ │ due ┆ 2026-10-15 │ │ status ┆ active │ │ tags ┆ [project, launch] │ ╰────────┴───────────────────╯ ``` ### `property get` Read one property value. ```bash octarine property get Projects/Launch.md status ``` ```text ╭───────┬────────╮ │ Field ┆ Value │ ╞═══════╪════════╡ │ key ┆ status │ │ value ┆ active │ ╰───────┴────────╯ ``` ### `property set` Set a frontmatter value. Values use YAML syntax, so quote shell-sensitive arrays or objects. The new value replaces the existing one in full, including a list written over several lines. Use `--revision` for an optimistic concurrency check. ```bash octarine property set Projects/Launch.md status active octarine property set Projects/Launch.md tags '[project, launch]' octarine property set Projects/Launch.md due 2026-10-15 \ --revision 'sha256:' ``` ```text ╭──────────┬─────────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪═════════════════════════════════╡ │ content ┆ ---\nstatus: active\n…\n---\n# Launch │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:9be317c2… │ ╰──────────┴─────────────────────────────────╯ ``` ### `property unset` Remove a property from one note, including every line of a multi-line value, optionally guarded by a revision. ```bash octarine property unset Projects/Launch.md legacy-status octarine property unset Projects/Launch.md due --revision 'sha256:' ``` ```text ╭──────────┬────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪════════════════════════════╡ │ content ┆ ---\nstatus: active\n---\n# Launch │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:84ff20da… │ ╰──────────┴────────────────────────────╯ ``` ## Raw Metadata `metadata` accesses JSON resources under `.octarine`. Prefer the typed `property`, `view`, `note-type`, `theme`, and `folder config` commands when one exists. ### `metadata list` Read a complete resource. `list` and `get` currently return the same stored JSON value. ```bash octarine metadata list views.json ``` ```text ╭─────────────────┬─────────────────┬─────────┬─────────┬───────────────┬───────────────╮ │ columns ┆ description ┆ filters ┆ id ┆ name ┆ modified │ ╞═════════════════╪═════════════════╪═════════╪═════════╪═══════════════╪═══════════════╡ │ [name, status] ┆ Current projects ┆ [] ┆ view-1 ┆ Active Projects ┆ 1790812800000 │ ╰─────────────────┴─────────────────┴─────────┴─────────┴───────────────┴───────────────╯ ``` ### `metadata get` Read a complete resource by filename. ```bash octarine metadata get types.json --json ``` ```text {"schemaVersion":1,"ok":true,"data":[{"created":1790812800000,"description":"Reading notes","id":"type-1","modified":1790812800000,"name":"Book","properties":[]}],"meta":{"truncated":false}} ``` ### `metadata put` Replace a resource with JSON or YAML from a file or standard input. ```bash octarine metadata put custom.json --file ./custom.json cat custom.yaml | octarine metadata put custom.json --file - ``` ```text ╭──────────┬─────────────╮ │ Field ┆ Value │ ╞══════════╪═════════════╡ │ resource ┆ custom.json │ ╰──────────┴─────────────╯ ``` This low-level command does not apply the typed resource validation described below. ## Views, Note Types, and Themes The `view`, `note-type`, and `theme` groups share a resource command set. Substitute any group for `` in the syntax below. IDs and names can both identify existing items. | Group | Portable store | Required shape | | --- | --- | --- | | `view` | `.octarine/views.json` | Description, filters, columns, timestamps | | `note-type` | `.octarine/types.json` | Description, properties, timestamps | | `theme` | `.octarine/themes.json` | Variables, dark flag, timestamps | ### ` list` List all items of one kind. ```bash octarine view list octarine note-type list --json octarine theme list ``` ```text # `view list` (the `theme list` shape includes theme fields instead) ╭────────┬─────────────────┬─────────┬───────────────╮ │ id ┆ name ┆ filters ┆ columns │ ╞════════╪═════════════════╪═════════╪═══════════════╡ │ view-1 ┆ Active Projects ┆ [] ┆ [name,status] │ ╰────────┴─────────────────┴─────────┴───────────────╯ # `note-type list --json` {"schemaVersion":1,"ok":true,"data":[{"created":1790812800000,"description":"Reading notes","id":"type-1","modified":1790812800000,"name":"Book","properties":[]}],"meta":{"truncated":false}} ``` ### ` get` Get one item by ID or name. ```bash octarine view get "Active Projects" octarine note-type get Book octarine theme get Midnight --json ``` ```text # Human output for `view get` / `note-type get` is a Field/Value table. ╭─────────────┬─────────────────╮ │ Field ┆ Value │ ╞═════════════╪═════════════════╡ │ id ┆ view-1 │ │ name ┆ Active Projects │ │ description ┆ Current projects │ │ filters ┆ [] │ │ columns ┆ name, status │ ╰─────────────┴─────────────────╯ # `theme get Midnight --json` {"schemaVersion":1,"ok":true,"data":{"baseTheme":null,"created":1790812800000,"dark":true,"id":"theme-1","modified":1790812800000,"name":"Midnight","variables":{"background":"#111318"}},"meta":{"truncated":false}} ``` ### ` create` Create a valid minimal item with generated ID and timestamps. ```bash octarine view create "Active Projects" octarine note-type create Book octarine theme create Midnight ``` ```text # Representative `view create` output; IDs and timestamps are generated. ╭─────────────┬─────────────────────╮ │ Field ┆ Value │ ╞═════════════╪═════════════════════╡ │ id ┆ views-1790812800… │ │ name ┆ Active Projects │ │ description ┆ │ │ filters ┆ [] │ │ columns ┆ [] │ │ created ┆ 1790812800000 │ │ modified ┆ 1790812800000 │ ╰─────────────┴─────────────────────╯ ``` ### ` update` Merge a JSON or YAML object into an existing item and refresh its modified timestamp. ```bash octarine view update "Active Projects" --file active-projects.yaml octarine note-type update Book --file book.json octarine theme update Midnight --file midnight.json ``` ```text # Representative `view update` output; modified varies by execution time. ╭─────────────┬─────────────────╮ │ Field ┆ Value │ ╞═════════════╪═════════════════╡ │ id ┆ view-1 │ │ name ┆ Active Projects │ │ description ┆ Current projects │ │ filters ┆ [] │ │ columns ┆ name, status │ │ modified ┆ 1790816400000 │ ╰─────────────┴─────────────────╯ ``` The merged resource must retain its required fields and pass type validation. ### ` validate` Validate all items or one item by ID or name. ```bash octarine view validate octarine note-type validate Book octarine theme validate Midnight ``` ```text ╭─────────┬───────╮ │ Field ┆ Value │ ╞═════════╪═══════╡ │ checked ┆ 1 │ │ valid ┆ true │ ╰─────────┴───────╯ ``` Validation also detects duplicate IDs and names. ### ` clone` Clone an item under a new unique name and generated ID. ```bash octarine view clone "Active Projects" --name "Active Projects Copy" octarine note-type clone Book --name Paper octarine theme clone Midnight --name "Midnight Blue" ``` ```text # Representative `view clone` output; IDs and timestamps are generated. ╭──────────┬──────────────────────╮ │ Field ┆ Value │ ╞══════════╪══════════════════════╡ │ id ┆ views-1790816400… │ │ name ┆ Active Projects Copy │ │ created ┆ 1790816400000 │ │ modified ┆ 1790816400000 │ ╰──────────┴──────────────────────╯ ``` ### `theme set` Set one custom theme variable. This operation is theme-only; `view set` and `note-type set` are rejected. ```bash octarine theme set Midnight background '#111318' octarine theme set Midnight accent 'rgb(120, 160, 255)' ``` ```text ╭───────────┬────────────────────────────────────────────────────╮ │ Field ┆ Value │ ╞═══════════╪════════════════════════════════════════════════════╡ │ name ┆ Midnight │ │ variables ┆ {"accent":"rgb(120, 160, 255)","background":"#111318"} │ │ dark ┆ true │ │ modified ┆ 1790816400000 │ ╰───────────┴────────────────────────────────────────────────────╯ ``` Theme values cannot contain braces or semicolons. ### `theme unset` Remove one custom theme variable. The syntax is `octarine theme unset `: ```bash octarine theme unset Midnight accent ``` ```text ╭───────────┬────────────────────────────╮ │ Field ┆ Value │ ╞═══════════╪════════════════════════════╡ │ name ┆ Midnight │ │ variables ┆ {"background":"#111318"} │ │ dark ┆ true │ │ modified ┆ 1790820000000 │ ╰───────────┴────────────────────────────╯ ``` ### ` put` Replace the complete array after validating every item. ```bash octarine view put --file views.json octarine note-type put --file types.yaml octarine theme put --file themes.json ``` ```text # Representative `view put` output ╭────────┬─────────────────┬─────────┬──────────────╮ │ id ┆ name ┆ filters ┆ columns │ ╞════════╪═════════════════╪═════════╪══════════════╡ │ view-1 ┆ Active Projects ┆ [] ┆ name, status │ ╰────────┴─────────────────┴─────────┴──────────────╯ ``` ### ` delete` Delete one item by ID or name. ```bash octarine view delete "Old View" octarine note-type delete Legacy octarine theme delete "Old Theme" ``` ```text # Representative `view delete` output: the remaining complete array. ╭────────┬─────────────────┬─────────┬──────────────╮ │ id ┆ name ┆ filters ┆ columns │ ╞════════╪═════════════════╪═════════╪══════════════╡ │ view-1 ┆ Active Projects ┆ [] ┆ name, status │ ╰────────┴─────────────────┴─────────┴──────────────╯ ``` ### ` schema` Describe the persisted resource family and format. ```bash octarine view schema octarine note-type schema --json octarine theme schema ``` ```text # `view schema` / `theme schema` ╭───────────────┬────────────╮ │ Field ┆ Value │ ╞═══════════════╪════════════╡ │ format ┆ json-array │ │ resource ┆ views │ │ schemaVersion ┆ 1 │ ╰───────────────┴────────────╯ # `note-type schema --json` {"schemaVersion":1,"ok":true,"data":{"format":"json-array","resource":"types","schemaVersion":1},"meta":{"truncated":false}} ```