# obclip
[中文说明](./README.zh-CN.md)
`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](./skills/obclip).
One-line install prompt for another your agent:
```text
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.md)
- [docs/install-obclip-skill.txt](./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:
```bash
npm install -g @harris7/obclip
obclip --help
```
Run without a global install:
```bash
npx @harris7/obclip --help
npx @harris7/obclip https://example.com
```
Project-local install:
```bash
npm install @harris7/obclip
npx @harris7/obclip https://example.com
```
If you want the default Playwright browser runtime, install Chromium once after package install:
```bash
npx playwright install chromium
```
If you always run with `--browser-executable`, the Playwright browser download is optional.
### Local Setup
```bash
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
```bash
npm run typecheck
npm test
```
## Quick Start
Run the installed package directly:
```powershell
obclip https://example.com
```
Run with `npx`:
```powershell
npx @harris7/obclip https://example.com
```
Run directly from the repository during development:
```powershell
node .\dist\cli.cjs https://example.com
```
Expose `obclip` as a local command on your machine:
```powershell
npm link
obclip https://example.com
```
## CLI Usage
```text
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:
```powershell
node .\dist\cli.cjs https://example.com/article
```
Write to a directory:
```powershell
node .\dist\cli.cjs https://example.com/article --output .\out\
```
Use a real Chromium executable:
```powershell
node .\dist\cli.cjs https://example.com/article --browser-executable "D:\app\chrome-win\chrome.exe"
```
Reuse login state with a dedicated browser profile:
```powershell
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:
```powershell
node .\dist\cli.cjs https://example.com/article --settle-ms 3000
```
Wait for a specific content container:
```powershell
node .\dist\cli.cjs https://example.com/article --wait-selector "article" --settle-ms 2000
```
Save and also open in Obsidian:
```powershell
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](./docs/agent-browser-waiting.md).
## Templates
If `--template` is omitted, `obclip` uses the built-in default template:
- [src/templates/default.json](./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:
```powershell
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:
```powershell
--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](./docs/template-boundaries.md).
## Project Docs
- [docs/install-obclip-skill.md](./docs/install-obclip-skill.md)
- [docs/agent-browser-waiting.md](./docs/agent-browser-waiting.md)
- [docs/publishing.md](./docs/publishing.md)
- [docs/template-boundaries.md](./docs/template-boundaries.md)
- [docs/vendor-maintenance.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](./docs/vendor-maintenance.md).