Metadata & Tags¶

VFS supports rich metadata for organizing and finding files through tags and custom key-value attributes.

Tags¶

Tags are labels you can attach to files for organization and quick retrieval.

Adding Tags¶

avfs tag <path> <tag>...

Examples:

# Single tag
avfs tag /docs/report.pdf important

# Multiple tags
avfs tag /docs/report.pdf important urgent work

Listing Tags¶

Tags on a file¶

$ avfs tag /docs/report.pdf --list
important, urgent, work

All tags in vault¶

$ avfs tag --list-all
TAG          COUNT
important    23
urgent       8
work         156
personal     45
code         234

Removing Tags¶

avfs untag <path> <tag>

Examples:

# Remove single tag
avfs untag /docs/report.pdf urgent

# Remove from pattern
avfs untag /archive/*.txt important

Finding Files by Tag¶

avfs find / --tag <tag>

Examples:

$ avfs find / --tag important
/docs/report.pdf
/config/production.yaml
/notes/meeting-2024-03-10.md

# Multiple tags (AND)
$ avfs find / --tag important --tag urgent
/docs/report.pdf

Managing Tags¶

# Create a new tag
avfs tag --create important

# Rename a tag
avfs tag --rename old-tag new-tag

# Delete a tag (removes from all files)
avfs tag --delete unused-tag

Custom Metadata¶

Beyond tags, you can store arbitrary key-value metadata on files.

Setting Metadata¶

avfs meta <path> <key> <value>

Examples:

# Set author
avfs meta /docs/report.pdf author "Jane Doe"

# Set multiple properties
avfs meta /docs/report.pdf department "Engineering"
avfs meta /docs/report.pdf status "draft"
avfs meta /docs/report.pdf priority "high"

# Numeric values
avfs meta /data/dataset.csv row_count "10000"

# Date values
avfs meta /docs/contract.pdf signed_date "2024-03-15"

Reading Metadata¶

# Get specific key
$ avfs meta /docs/report.pdf author
Jane Doe

# Get all metadata
$ avfs meta /docs/report.pdf
KEY          VALUE
author       Jane Doe
department   Engineering
status       draft
priority     high

Removing Metadata¶

avfs meta /docs/report.pdf --delete status

Finding by Metadata¶

avfs find / --meta <key>=<value>

Examples:

# Find by author
$ avfs find / --meta author="Jane Doe"
/docs/report.pdf
/docs/presentation.pdf

# Find by status
$ avfs find / --meta status=draft
/docs/report.pdf
/src/feature.rs

Export/Import Metadata¶

# Export metadata to JSON
avfs meta /docs/ --export > metadata.json

# Import metadata from JSON
avfs meta --import metadata.json

JSON format:

{
  "/docs/report.pdf": {
    "tags": ["important", "work"],
    "metadata": {
      "author": "Jane Doe",
      "status": "draft"
    }
  }
}

Use Cases¶

Project Organization¶

# Set up project tags
avfs tag --create frontend
avfs tag --create backend
avfs tag --create docs

# Tag project files
avfs tag /src/ui/*.tsx frontend
avfs tag /src/api/*.rs backend
avfs tag /docs/*.md docs

# Find all frontend code
avfs find / --tag frontend

Document Management¶

# Track document metadata
avfs meta /contracts/client-a.pdf client "Acme Corp"
avfs meta /contracts/client-a.pdf value "50000"
avfs meta /contracts/client-a.pdf expires "2025-12-31"

Research Notes¶

# Organize research
avfs tag /notes/paper-1.md read cite
avfs meta /notes/paper-1.md source "arxiv:2024.12345"
avfs meta /notes/paper-1.md relevance "high"

# Find papers to cite
avfs find /notes --tag cite