Skip to content

cli-extract.md

Latest commit

 

History

History
199 lines (137 loc) · 5.19 KB

cli-extract.md

File metadata and controls

199 lines (137 loc) · 5.19 KB
Raw

IWE Extract

Extract a section from a document into a new document with an Inclusion Links.

Usage

iwe extract <KEY> [OPTIONS]

Arguments

Argument Description
<KEY> Document key containing the section to extract

Options

Flag Description
--section <TITLE> Section title to extract (case-insensitive)
--block <N> Block number to extract (1-indexed)
--list List all sections with block numbers
--action <NAME> Action name from config to use for extraction
--dry-run Preview changes without writing to disk
--quiet Suppress progress output
-f, --format <FMT> Output format: markdown (default) or keys (print affected document keys, one per line)

How It Works

The extract command creates a new document from an existing section:

  1. Select a section - Use --list to see available sections, then select with --section or --block
  2. Create new document - The section content is moved to a new document
  3. Add inclusion link - The original section is replaced with a link to the new document
  4. Adjust headers - Header levels are adjusted to maintain proper document structure

Workflow

Step 1: List Available Sections

$ iwe extract my-document --list
1: Introduction
2: Getting Started
3: Configuration
4: Advanced Topics

Step 2: Extract by Title or Block Number

# By title (case-insensitive, partial match)
$ iwe extract my-document --section "configuration"
Extracting section 'Configuration' to 'configuration'
Done

# By block number (unambiguous)
$ iwe extract my-document --block 3
Extracting section 'Configuration' to 'configuration'
Done

Configuration

The --action flag uses extraction settings from .iwe/config.toml:

[actions]
extract = { type = "extract", title = "Extract", key_template = "{{slug}}", link_type = "markdown" }

Without --action, the command uses the first extract action found in config, or defaults to:

  • key_template = "{{slug}}" - URL-friendly version of the section title
  • link_type = "markdown" - Standard markdown links

Key Template Variables

See feature-extract.md for all available template variables.

Output Modes

Default Output

Shows progress:

$ iwe extract my-document --section "Architecture"
Extracting section 'Architecture' to 'architecture'
Done

Dry Run (--dry-run)

Preview what would happen:

$ iwe extract my-document --section "Design" --dry-run
Would extract section 'Design' to 'design'
Would update 'my-document'

Keys Output (-f keys)

Print affected document keys:

$ iwe extract my-document --block 2 -f keys
my-document
getting-started

Examples

# List all sections with block numbers
iwe extract notes/project --list

# Extract section by title
iwe extract notes/project --section "Architecture"

# Extract section by block number (unambiguous)
iwe extract notes/project --block 2

# Preview changes without writing
iwe extract notes/project --section "Notes" --dry-run

# Use a specific action from config
iwe extract notes/project --section "Design" --action "my-extract"

# Get keys for scripting
iwe extract notes/project --section "API" -f keys

Use Cases

Breaking Down Large Documents

Extract sections to create a modular document structure:

# See what sections exist
iwe extract large-document --list

# Extract each major section
iwe extract large-document --section "Introduction"
iwe extract large-document --section "Implementation"
iwe extract large-document --section "Testing"

Organizing by Topic

Move related content to dedicated documents:

# Preview the extraction
iwe extract project-notes --section "Authentication" --dry-run

# Extract to a dedicated document
iwe extract project-notes --section "Authentication"

Scripting

Use with other commands:

# Extract and get the new document key
NEW_KEY=$(iwe extract doc --section "API" -f keys | tail -1)
echo "Created: $NEW_KEY"

Error Handling

The command fails with an error if:

  • The document does not exist
  • No section matches the provided title (with --section)
  • Multiple sections match the title (use --block instead)
  • The block number is out of range (with --block)
  • Must specify --section, --block, or --list

Key Collision Handling

When the generated key already exists, IWE automatically appends numeric suffixes:

  1. First attempt: architecture.md
  2. If exists: architecture-1.md
  3. If exists: architecture-2.md

Technical Notes

  • Header levels are adjusted automatically (H2 in source becomes H1 in extracted document)
  • The original section is replaced with an inclusion link
  • The command uses the same extraction logic as the LSP code action
  • Directory structure is preserved based on the source document location