---
title: Folders, Links, Tasks, and Tags
description: Complete CLI reference for folder operations, wikilink inspection, workspace tasks, and tags.
---

## Folder Commands

Folder paths are relative to the selected workspace. Folder moves and renames update every link to the notes inside the folder.

### `folder create`

Create a folder and any required parents.

```bash
octarine folder create Projects/Launch
```

```text
╭───────┬─────────────────╮
│ Field ┆ Value           │
╞═══════╪═════════════════╡
│ path  ┆ Projects/Launch │
╰───────┴─────────────────╯
```

### `folder list`

List every folder, or scope results to one subtree.

```bash
octarine folder list
octarine folder list Projects
```

```text
# All folders
╭──────────────────╮
│ Value            │
╞══════════════════╡
│ Archive          │
│ Projects         │
│ Projects/Launch  │
╰──────────────────╯

# Projects subtree
╭──────────────────╮
│ Value            │
╞══════════════════╡
│ Projects         │
│ Projects/Launch  │
╰──────────────────╯
```

### `folder move`

Move a folder and rewrite links to every note inside it. Preview the operation with `--dry-run`.

```bash
octarine folder move Drafts/Launch Projects/Launch --dry-run
octarine folder move Drafts/Launch Projects/Launch
```

```text
# Dry run
╭──────────────┬─────────────────╮
│ Field        ┆ Value           │
╞══════════════╪═════════════════╡
│ dryRun       ┆ true            │
│ from         ┆ Drafts/Launch   │
│ linksUpdated ┆ 1               │
│ to           ┆ Projects/Launch │
│ updated      ┆ Home.md         │
╰──────────────┴─────────────────╯

# Move
╭──────────────┬─────────────────╮
│ Field        ┆ Value           │
╞══════════════╪═════════════════╡
│ dryRun       ┆ false           │
│ from         ┆ Drafts/Launch   │
│ linksUpdated ┆ 1               │
│ to           ┆ Projects/Launch │
│ updated      ┆ Home.md         │
╰──────────────┴─────────────────╯
```

### `folder rename`

`rename` has the same behavior and syntax as `move`, but communicates that the destination is a new name.

Both commands rewrite the same link forms as [`note rename`](/cli/notes#note-rename): path and unique-name wikilinks, embeds, `#heading` and `|alias` suffixes, frontmatter links, and relative Markdown links. Links inside code are left alone.

```bash
octarine folder rename Projects/Launch Projects/Release --dry-run
octarine folder rename Projects/Launch Projects/Release
```

```text
# Dry run
╭──────────────┬──────────────────╮
│ Field        ┆ Value            │
╞══════════════╪══════════════════╡
│ dryRun       ┆ true             │
│ from         ┆ Projects/Launch  │
│ linksUpdated ┆ 1                │
│ to           ┆ Projects/Release │
│ updated      ┆ Home.md          │
╰──────────────┴──────────────────╯

# Rename
╭──────────────┬──────────────────╮
│ Field        ┆ Value            │
╞══════════════╪══════════════════╡
│ dryRun       ┆ false            │
│ from         ┆ Projects/Launch  │
│ linksUpdated ┆ 1                │
│ to           ┆ Projects/Release │
│ updated      ┆ Home.md          │
╰──────────────┴──────────────────╯
```

### `folder duplicate`

Copy a complete folder. Omit the destination to use a generated copy path; `--unique` prevents collisions.

```bash
octarine folder duplicate Projects/Template Projects/New-project
octarine folder duplicate Projects/Template --unique
```

```text
# Exact destination
Projects/New-project

# Generated unique destination
Projects/Template copy
```

### `folder trash`

Move a folder to the operating system trash. The protected `.octarine` folder cannot be trashed this way.

```bash
octarine folder trash Archive/Obsolete
```

```text
╭─────────┬──────────────────╮
│ Field   ┆ Value            │
╞═════════╪══════════════════╡
│ trashed ┆ Archive/Obsolete │
╰─────────┴──────────────────╯
```

### `folder config get`

Read one folder's configuration. SQLite is preferred for a registered workspace, with `.octarine/folder-config.json` as the portable fallback.

```bash
octarine folder config get Projects
octarine folder config get Projects --json
```

```text
# Table output
╭────────┬─────────────────╮
│ Field  ┆ Value           │
╞════════╪═════════════════╡
│ config ┆ {"sort":"name"} │
│ path   ┆ Projects        │
╰────────┴─────────────────╯

# JSON output
{"schemaVersion":1,"ok":true,"data":{"path":"Projects","config":{"sort":"name"}},"meta":{"truncated":false}}
```

### `folder config set`

Replace one folder's configuration from a JSON or YAML object. Use `--file -` for standard input.

```bash
octarine folder config set Projects --file folder-config.yaml
printf '{"sort":"name"}' | octarine folder config set Projects --file -
```

```text
╭─────────┬──────────╮
│ Field   ┆ Value    │
╞═════════╪══════════╡
│ path    ┆ Projects │
│ updated ┆ true     │
╰─────────┴──────────╯
```

The portable file and compatible SQLite row are updated together.

## Link Commands

Link commands read wikilinks, embeds, frontmatter links, and relative Markdown links, and resolve each one to a note the same way the desktop app does: paths are case-insensitive, and a bare note name resolves when exactly one note has that name. Links inside code are ignored.

Each link result includes:

| Field | Meaning |
| --- | --- |
| `source` | Note containing the link |
| `line` | One-based line number |
| `kind` | `wiki` or `markdown` (`mention` for `link mentions`) |
| `target` | Link target as written, without its heading or alias |
| `fragment` | `#heading` part of the link, when present |
| `resolved` | Workspace path the link points to, or `null` when unresolved |

### `link list`

List all links, or links originating in one note.

```bash
octarine link list
octarine link list Home.md --json
```

```text
# All links
╭──────────┬──────┬────────────────────┬────────────┬────────────────────┬──────────╮
│ kind     ┆ line ┆ resolved           ┆ source     ┆ target             ┆ fragment │
╞══════════╪══════╪════════════════════╪════════════╪════════════════════╪══════════╡
│ wiki     ┆ 3    ┆ —                  ┆ Ideas.md   ┆ Release checklist  ┆ —        │
│ wiki     ┆ 3    ┆ Projects/Launch.md ┆ Home.md    ┆ Projects/Launch    ┆ Goals    │
│ wiki     ┆ 3    ┆ Roadmap.md         ┆ Home.md    ┆ Roadmap            ┆ —        │
│ markdown ┆ 3    ┆ Projects/Launch.md ┆ Roadmap.md ┆ Projects/Launch.md ┆ —        │
╰──────────┴──────┴────────────────────┴────────────┴────────────────────┴──────────╯

# Links from one note (JSON)
{"schemaVersion":1,"ok":true,"data":[{"source":"Home.md","line":3,"kind":"wiki","target":"Projects/Launch","fragment":"Goals","resolved":"Projects/Launch.md"},{"source":"Home.md","line":3,"kind":"wiki","target":"Roadmap","resolved":"Roadmap.md"}],"meta":{"truncated":false}}
```

### `link backlinks`

Find links that resolve to a note, whatever form they are written in.

```bash
octarine link backlinks Projects/Launch.md
```

```text
╭──────────┬──────┬────────────────────┬────────────┬────────────────────┬──────────╮
│ kind     ┆ line ┆ resolved           ┆ source     ┆ target             ┆ fragment │
╞══════════╪══════╪════════════════════╪════════════╪════════════════════╪══════════╡
│ wiki     ┆ 3    ┆ Projects/Launch.md ┆ Home.md    ┆ Projects/Launch    ┆ Goals    │
│ markdown ┆ 3    ┆ Projects/Launch.md ┆ Roadmap.md ┆ Projects/Launch.md ┆ —        │
╰──────────┴──────┴────────────────────┴────────────┴────────────────────┴──────────╯
```

### `link replace`

Rewrite every link that resolves to one note so it points to another.

```bash
octarine link replace Projects/Launch Projects/Release
```

```text
╭──────────────┬─────────────────────╮
│ Field        ┆ Value               │
╞══════════════╪═════════════════════╡
│ dryRun       ┆ false               │
│ from         ┆ Projects/Launch     │
│ linksUpdated ┆ 2                   │
│ to           ┆ Projects/Release    │
│ updated      ┆ Home.md, Roadmap.md │
╰──────────────┴─────────────────────╯
```

### `link unresolved`

List links whose target cannot be resolved. `link broken` is an alias.

```bash
octarine link unresolved
octarine link broken --json
```

```text
# Table output
╭──────┬──────┬──────────┬──────────┬───────────────────╮
│ kind ┆ line ┆ resolved ┆ source   ┆ target            │
╞══════╪══════╪══════════╪══════════╪═══════════════════╡
│ wiki ┆ 3    ┆ —        ┆ Ideas.md ┆ Release checklist │
╰──────┴──────┴──────────┴──────────┴───────────────────╯

# JSON output
{"schemaVersion":1,"ok":true,"data":[{"source":"Ideas.md","line":3,"kind":"wiki","target":"Release checklist","resolved":null}],"meta":{"truncated":false}}
```

### `link orphans`

List notes with no incoming links.

```bash
octarine link orphans
```

```text
╭───────────────────╮
│ Value             │
╞═══════════════════╡
│ Scratch/Ideas.md  │
╰───────────────────╯
```

### `link deadends`

List notes with no outgoing links.

```bash
octarine link deadends
```

```text
╭──────────────────────────╮
│ Value                    │
╞══════════════════════════╡
│ Projects/Release-notes.md│
╰──────────────────────────╯
```

### `link mentions`

Find plain-text mentions of a name that are not links. `resolved` is set when a note with that name exists.

```bash
octarine link mentions "Launch plan"
```

```text
╭─────────┬──────┬──────────┬────────────┬─────────────╮
│ kind    ┆ line ┆ resolved ┆ source     ┆ target      │
╞═════════╪══════╪══════════╪════════════╪═════════════╡
│ mention ┆ 9    ┆ —        ┆ Roadmap.md ┆ Launch plan │
╰─────────┴──────┴──────────┴────────────┴─────────────╯
```

## Workspace Tasks

### `task list`

List Markdown tasks across all notes. Filter by folder or completion state; `--done` and `--todo` are mutually exclusive.

```bash
octarine task list
octarine task list --folder Projects --todo
octarine task list --done --json
```

```text
# All workspace tasks
╭─────────┬────┬──────┬────────────────────┬─────────────────────╮
│ checked ┆ id ┆ line ┆ path               ┆ text                │
╞═════════╪════╪══════╪════════════════════╪═════════════════════╡
│ false   ┆ 12 ┆ 12   ┆ Projects/Launch.md ┆ Announce release    │
│ true    ┆ 13 ┆ 13   ┆ Projects/Launch.md ┆ Prepare screenshots │
╰─────────┴────┴──────┴────────────────────┴─────────────────────╯

# Open tasks below Projects
╭─────────┬────┬──────┬────────────────────┬──────────────────╮
│ checked ┆ id ┆ line ┆ path               ┆ text             │
╞═════════╪════╪══════╪════════════════════╪══════════════════╡
│ false   ┆ 12 ┆ 12   ┆ Projects/Launch.md ┆ Announce release │
╰─────────┴────┴──────┴────────────────────┴──────────────────╯

# Completed tasks (JSON)
{"schemaVersion":1,"ok":true,"data":[{"path":"Projects/Launch.md","id":13,"line":13,"checked":true,"text":"Prepare screenshots"}],"meta":{"truncated":false}}
```

Use [`note task set`](/cli/notes#note-task-set) to change an individual task.

## Workspace Tags

### `tag list`

List tags with occurrence counts. Sort by descending count when auditing common tags.

```bash
octarine tag list
octarine tag list --sort-count --json
```

```text
# Table output
╭───────┬──────────╮
│ count ┆ tag      │
╞═══════╪══════════╡
│ 3     ┆ #launch  │
│ 5     ┆ #project │
╰───────┴──────────╯

# Count-sorted JSON output
{"schemaVersion":1,"ok":true,"data":[{"tag":"#project","count":5},{"tag":"#launch","count":3}],"meta":{"truncated":false}}
```