obclip-skill

obclip

中文说明

obclip is a local CLI for clipping live web pages into Obsidian-compatible notes.

Published package name: @harris7/obclip Installed command name: obclip

It follows the same high-level execution path as the Obsidian Clipper extension:

URL -> live DOM extraction -> template build -> stdout / file / Obsidian

This repository is intentionally CLI-first. It is built for agents, scripts, and local automation, not for browser extension UI or cloud workflows.

Agent Skill

This repo also ships an installable skill at skills/obclip.

One-line install prompt for another your agent:

Use $skill-installer to install the skill from https://github.com/Rycen7822/obclip-skill/tree/main/skills/obclip

Install entrypoint files:

• docs/install-obclip-skill.md
• docs/install-obclip-skill.txt

Highlights

• Extracts the live DOM through Playwright instead of relying on raw fetched HTML.
• Builds Markdown with an Obsidian-Clipped-compatible template shape.
• Supports stdout, file output, and Obsidian open flows.
• Can run with Playwright Chromium or a real Chromium-family browser executable.
• Supports persistent browser profiles for sites that require login state.

Installation

Requirements

• Node.js >= 18
• Obsidian desktop app if you want to use --open
• A browser runtime:
  • Playwright Chromium in default mode
  • or your own Chromium-family executable via --browser-executable

Install From npm

Global install:

npm install -g @harris7/obclip
obclip --help

Run without a global install:

npx @harris7/obclip --help
npx @harris7/obclip https://example.com

Project-local install:

npm install @harris7/obclip
npx @harris7/obclip https://example.com

If you want the default Playwright browser runtime, install Chromium once after package install:

npx playwright install chromium

If you always run with --browser-executable, the Playwright browser download is optional.

Local Setup

npm install
npx playwright install chromium
npm run build

If you always run with --browser-executable, the npx playwright install chromium step is optional.

Development Checks

npm run typecheck
npm test

Quick Start

Run the installed package directly:

obclip https://example.com

Run with npx:

npx @harris7/obclip https://example.com

Run directly from the repository during development:

node .\dist\cli.cjs https://example.com

Expose obclip as a local command on your machine:

npm link
obclip https://example.com

CLI Usage

obclip <url> [--template <file|dir>] [--output <path>] [--open] [--vault <name>] [--uri] [--silent]
             [--browser-executable <path>] [--browser-profile <dir>] [--headful]
             [--settle-ms <ms>] [--wait-selector <css>]
obclip --help
obclip --version

Options

• --template <file|dir>: load one template JSON file or recursively load all JSON files under a directory.
• --output <path>: write Markdown to disk instead of stdout.
• --open: send the built note to Obsidian.
• --vault <name>: override the template vault when opening in Obsidian.
• --uri: force obsidian:// URI mode even if the Obsidian CLI is available.
• --silent: pass silent mode to the URI fallback path.
• --browser-executable <path>: launch a specific Chromium-family executable instead of Playwright's bundled browser.
• --browser-profile <dir>: launch a persistent browser profile directory.
• --headful: run the browser with UI instead of headless mode.
• --settle-ms <ms>: wait extra milliseconds after navigation before extraction starts.
• --wait-selector <css>: wait for a specific DOM selector before extraction starts.

Examples

Default mode:

node .\dist\cli.cjs https://example.com/article

Write to a directory:

node .\dist\cli.cjs https://example.com/article --output .\out\

Use a real Chromium executable:

node .\dist\cli.cjs https://example.com/article --browser-executable "D:\app\chrome-win\chrome.exe"

Reuse login state with a dedicated browser profile:

node .\dist\cli.cjs https://example.com/article --browser-executable "D:\app\chrome-win\chrome.exe" --browser-profile "D:\obclip-profile" --headful

Handle a slow SPA:

node .\dist\cli.cjs https://example.com/article --settle-ms 3000

Wait for a specific content container:

node .\dist\cli.cjs https://example.com/article --wait-selector "article" --settle-ms 2000

Save and also open in Obsidian:

node .\dist\cli.cjs https://example.com/article --output .\out\ --open --vault Work

Browser Modes

Default Mode

• Uses Playwright's bundled Chromium.
• Uses a temporary browser context.
• Does not keep login state between runs.
• Best for public pages and simple automation.

Real Chromium Mode

Enable this mode with --browser-executable.

• Uses your own Chromium-family browser binary.
• Can reuse login state with --browser-profile.
• Can run with --headful when you need to inspect rendering or log in manually.

Do not point --browser-profile at your daily Chrome default profile. Use a dedicated directory for obclip.

Waiting Strategy

Before extraction starts, obclip waits in three layers:

1. page navigation
2. browser ready state
3. content-root readiness

Content-root readiness works like this:

• If --wait-selector is provided, obclip waits for that selector.
• Otherwise it runs a small built-in auto-wait heuristic.
• After either path, --settle-ms still applies as an extra fixed delay.

Practical rule of thumb:

• Use --settle-ms when the page is simply slow.
• Use --wait-selector when the page shell appears early but the real content mounts later.
• Use --browser-profile when the site requires login.

Detailed agent guidance lives in docs/agent-browser-waiting.md.

Templates

If --template is omitted, obclip uses the built-in default template:

• src/templates/default.json

If --template points to a file:

• The file may contain one template object.
• The file may contain an array of template objects.

If --template points to a directory:

• All *.json files are loaded recursively.
• Files are sorted by path before loading.
• Template selection order is:
  1. first matching trigger
  2. only triggerless template
  3. explicit error if still ambiguous or nothing matches

Trigger behavior:

• String triggers use URL prefix matching.
• Regex triggers use /.../.
• Schema triggers use upstream-compatible schema: handling.

Output Behavior

Default output is stdout, which is the most pipe-friendly mode.

When --output succeeds, obclip prints the final saved file path to stderr so stdout can remain clean for piping.

If --output points to a directory:

• The note is written as <output>/<template path>/<sanitized note name>.md.

If --output points to a file:

• That exact file is overwritten.

Windows path note:

• D:\data\Clippings\ is always treated as a directory.
• D:\data\Clippings is treated as a directory only if it already exists.
• If D:\data\Clippings does not exist yet, the current implementation treats it as a file path.

--open behavior:

• obclip prefers the vendored upstream openInObsidian() flow.
• If the obsidian CLI exists on PATH, that path is used unless --uri is set.
• Otherwise it falls back to obsidian://.

--output and --open can be used together.

Troubleshooting

obclip command not found

obclip is available as a shell command only when the package is globally installed or linked.

Use one of these:

obclip https://example.com
npx @harris7/obclip https://example.com
npm install -g @harris7/obclip
node .\dist\cli.cjs https://example.com
npm link
obclip https://example.com

Saved note is incomplete

Typical causes:

• The site is still hydrating.
• The site requires login.
• The page shell appeared before the real content.

Try this order:

1. add --settle-ms
2. add --wait-selector
3. switch to --browser-profile
4. add --headful to inspect what the browser actually rendered

Page works in the browser extension but not in CLI

That usually means the extension is clipping an already-open, already-authenticated browser page, while the CLI is starting a fresh automated browser session.

Typical fixes:

• use a dedicated persistent browser profile
• use a real Chromium executable
• add more wait time or an explicit wait selector

Output path on Windows behaves like a file

If you want a new directory target, make it explicit:

--output "D:\data\Clippings\"

If the path does not exist and does not end with \, the current implementation may treat it as a file path.

Scope

Supported today:

• live DOM extraction through Playwright Chromium
• explicit Chromium executable support
• dedicated persistent profile support
• upstream-compatible template shape
• template directory auto-match by URL or schema trigger
• stdout, file output, and Obsidian open flows

Explicitly out of scope:

• browser extension popup, side panel, or settings UI
• highlight persistence
• prompt or interpreter execution
• Chrome Sync migration
• cookie import or login-state injection
• screenshots or share flows
• public --html or --json modes
• alternate browser backends

Detailed boundaries live in docs/template-boundaries.md.

Project Docs

• docs/install-obclip-skill.md
• docs/agent-browser-waiting.md
• docs/publishing.md
• docs/template-boundaries.md
• docs/vendor-maintenance.md

Development Notes

obclip vendors upstream Obsidian Clipper logic under vendor/obsidian-clipper and keeps CLI-specific adaptations in src/.

Maintenance rules and upgrade workflow live in docs/vendor-maintenance.md.