Skip to content
BranchesTags

Repository files navigation

Recurl

Recurl은 native curl 호출을 유지하면서 output formatting, HTML sanitization, 선택적 browser rendering을 제공하는 CLI입니다.

Install

Homebrew 사용

Homebrew와 Bun(빌드에 사용됨)이 필요합니다.

custom tap을 등록한 뒤 formula를 설치합니다.

brew tap miyu4u/tap https://github.com/miyu4u/homebrew-tap
brew install miyu4u/tap/recurl

설치가 끝나면 다음 명령으로 CLI를 확인할 수 있습니다.

recurl --recurl-version

현재 formula는 설치 과정에서 bun으로 소스를 빌드하므로 별도로 바이너리를 내려받지 않습니다.

직접 빌드

Git과 Bun을 준비한 뒤 repository를 clone하고 의존성을 설치합니다.

git clone https://github.com/miyu4u/recurl.git
cd recurl
bun install --frozen-lockfile
bun run build

빌드된 실행 파일은 dist/recurl에 생성됩니다.

./dist/recurl --help

Quick Start

recurl은 일반적인 curl 명령을 그대로 전달하면서 필요할 때 결과를 텍스트, Markdown, JSON 또는 정제된 HTML로 바꿉니다.

# curl과 같은 raw 응답
recurl https://example.com

# HTML을 읽기 쉬운 plain text로 변환
recurl --recurl-output text https://example.com

# 본문을 정제한 뒤 article 영역만 Markdown으로 변환
recurl --recurl-output markdown \
  --recurl-sanitize-mode readable \
  --recurl-sanitize-selector article \
  https://example.com

기존 curl option은 recurl option과 함께 사용할 수 있습니다.

recurl --fail --location https://example.com
recurl --recurl-net-policy allowlist \
  --recurl-allowed-domain example.com \
  https://example.com

Recurl option은 첫 번째 literal -- 앞에서만 해석합니다. 그 뒤의 token은 --recurl-*를 포함해 원래 순서대로 curl에 전달됩니다.

호환 사항

구성 요소 지원 계약
Bun 개발 및 빌드에 Bun >=1.3.14가 필요합니다. bun.lock을 사용합니다.
curl 특정 최소 버전을 고정하지 않습니다. OS 또는 사용자가 제공하는 native curl을 사용하며, 설치된 curl이 요청한 curl option을 지원해야 합니다.
curl 경로 --recurl-curl-path, RECURL_CURL, PATH 순서로 executable을 찾습니다.
CloakBrowser optional dependency cloakbrowser ^0.4.8 경로를 지원합니다. 기본 cache는 ~/.cloakbrowser이며 CLOAKBROWSER_BINARY_PATH, CLOAKBROWSER_CACHE_DIR로 바꿀 수 있습니다.
Chrome/Chromium chrome-cdp에서 실행 중인 CDP endpoint에 연결하거나 명시한 executable을 실행해야 합니다.
Camofox @askjo/camofox-browser server URL 또는 operator가 준비한 executable이 필요합니다.

Browser renderer는 기본값이 아니며 각 provider와 browser runtime을 별도로 준비해야 합니다.

Browser renderer를 사용하지 않는 기본 경로에는 native curl만 필요합니다.

배경

터미널을 사용하는 대부분의 모델은 curl 또는 wget을 사용합니다.

여러 harness가 각자 web_fetch, web_extract, fetch 같은 인터넷 접근 tool을 제공하지만, 하네스 자체의 별도 제약이 없다면 모델은 보통 bash를 통해 curl을 실행합니다.

curl에 부족한 web extraction, security, lazy page rendering 기능도 많은 harness가 제공하지만, policy와 configuration은 harness마다 다릅니다.

여러 harness를 함께 쓰는 환경에서 이를 일관되게 적용하기 위해 recurl을 만들었습니다.

이 CLI 가 달성하고자 하는 목적

Recurl의 핵심 목적은 curl을 다른 API로 대체하는 것이 아니라, native curl의 익숙한 command-line contract를 유지한 채 AI harness와 터미널 사용에 필요한 공통 동작을 한 곳에서 제공하는 것입니다.

  • 호환성: curl option, stdin/stdout/stderr, child exit code를 기본 passthrough 경로에서 보존합니다.
  • 읽기성: HTML 응답을 text, Markdown, JSON, HTML로 일관되게 변환합니다.
  • 안전 경계: 필요할 때 network policy와 HTML sanitization을 명시적으로 적용합니다.
  • 선택적 렌더링: JavaScript와 lazy load가 필요한 페이지에만 Chrome CDP, CloakBrowser, Camofox를 opt-in으로 사용합니다.
  • 예측 가능성: recurl 고유 option과 upstream curl/provider 오류를 구분해 진단합니다.

지원되는 기능

  • Native curl passthrough
  • HTML sanitization 및 CSS selector narrowing
  • raw, html, text, markdown, json output
  • chrome-cdp, cloakbrowser, camofox browser renderer
  • curl, local-safe, deny-private, allowlist network policy
  • renderer worker environment allowlist
  • recurl/curl 통합 help와 resolved curl command 출력

Native curl passthrough

아무 output 또는 sanitization option을 지정하지 않으면 recurl은 native curl을 직접 실행합니다.

stdin/stdout/stderr를 연결하고, 완료된 curl child의 exit code를 그대로 반환합니다.

recurl --fail --location https://example.com
recurl --recurl-print-curl --location https://example.com

Output formatting

--recurl-output으로 응답 표현을 선택합니다.

기본값은 raw이며, html은 정제된 HTML, text는 plain text, markdown은 turndown 기반 Markdown, json은 {"mode":"json","content":"..."} envelope를 출력합니다.

recurl --recurl-output text https://example.com
recurl --recurl-output markdown https://example.com
recurl --recurl-output json https://example.com

HTML sanitization

--recurl-sanitize-mode strict|readable은 curl 또는 browser renderer의 HTML을 capture한 뒤 선택적으로 subtree를 좁히고, unsafe element와 attribute를 제거한 뒤 serialize합니다.

readable은 heading, paragraph, list 같은 읽기 구조를 더 보존하고, strict는 불필요한 wrapper와 content를 더 적극적으로 제거합니다.

recurl --recurl-sanitize-mode readable \
  --recurl-output text https://example.com
recurl --recurl-sanitize-mode strict \
  --recurl-sanitize-selector main \
  --recurl-output html https://example.com

이 기능은 HTML/XSS rendering cleanup이며 prompt injection detector가 아닙니다.

--recurl-sanitize-selector의 match가 없으면 recurl 오류로 실패합니다.

Browser rendering

JavaScript 실행이나 lazy load가 필요한 페이지에만 renderer를 명시합니다.

Browser 경로는 하나의 명시적 HTTP(S) target URL과 선택적 -L 또는 --location만 지원하며, 그 밖의 curl option은 거절합니다.

recurl --recurl-renderer chrome-cdp \
  --recurl-browser-url http://127.0.0.1:9222 \
  --recurl-output text https://example.com
recurl --recurl-renderer cloakbrowser \
  --recurl-output markdown https://example.com
recurl --recurl-renderer camofox \
  --recurl-camofox-url http://127.0.0.1:9377 \
  --recurl-output text https://example.com

chrome-cdp는 --recurl-browser-url, --recurl-browser-ws-endpoint, --recurl-chrome-launch 중 하나를 사용합니다.

camofox는 --recurl-camofox-url 또는 --recurl-camofox-launch 중 하나를 사용합니다.

Network policy

기본 curl policy는 기존 호환 경로를 유지합니다. local-safe, deny-private, allowlist는 하나의 명시적 HTTP(S) target만 허용하고, private/local destination, proxy environment, 위험한 transport 및 destination rewrite option을 검사합니다.

allowlist는 exact 또는 subdomain hostname match를 사용합니다.

recurl --recurl-net-policy local-safe https://example.com
recurl --recurl-net-policy allowlist \
  --recurl-allowed-domain example.com \
  https://example.com

이 policy는 defense-in-depth guard이며 온전한 egress sandbox가 아닙니다. Browser renderer traffic에는 적용되지 않습니다.

Renderer worker isolation

Browser worker에는 기본적으로 PATH, HOME, temporary directory, browser/provider override 등 allowlist 환경변수만 전달합니다. provider가 추가 환경변수를 요구하는 경우에만 --recurl-renderer-env-pass-through를 사용하세요.

이 option은 현재 shell의 credential-bearing environment까지 worker에 전달할 수 있습니다.

설정

설정은 선택적인 environment variable로 전달합니다.

Environment variable은 local input으로만 사용합니다. RECURL_CURL, RECURL_CAMOFOX_ACCESS_KEY(또는 CAMOFOX_ACCESS_KEY), CLOAKBROWSER_BINARY_PATH, CLOAKBROWSER_CACHE_DIR를 지원합니다.

작동 원리 및 구조

Recurl은 CLI 경계에서 option을 parse하고, runtime에서 선택한 실행 경로를 호출하며, output 계층에서 HTML 변환을 담당합니다.

Browser renderer는 compiled executable 안의 private worker에서 provider별로 선택적으로 load됩니다.

코드 구조

[src/main.ts]
      |
      v
[src/commands] ---> [src/diagnostics]
      |
      v
[src/runtime] ----> [src/output]
      |
      +--> [curl executor]
      |
      +--> [renderer worker]
              |
              +--> chrome-cdp
              +--> cloakbrowser
              +--> camofox

commands는 입력 경계와 dispatch, runtime은 curl/provider 실행과 network policy를 담당하며, output은 selector narrowing, sanitization, serialization을 담당합니다.

명령 실행 시 데이터 전파

argv
  |
  v
parse before first "--" ----> literal curl payload
  |
  v
validate command
  |
  +--> curl ----> stdout/stderr + exit code
  |
  +--> browser worker ----> rendered HTML
                              |
                              v
                 capture -> selector -> sanitize -> serialize
                              |
                              v
                         stdout result

raw와 sanitization이 꺼진 curl 경로는 capture 없이 stream을 연결합니다.

그 외 curl output과 모든 browser output은 필요한 경우 capture한 뒤 UTF-8 HTML pipeline을 거칩니다.

업스트림 오류 전파

curl / browser / provider
          |
          v
   runtime result or error
          |
          +--> upstream child exit code
          |          |
          |          v
          |      stdout/stderr
          |
          +--> recurl-owned failure
                     |
                     v
              diagnostic -> stderr
                     |
                     v
                   exit 127

사용법 또는 configuration 오류는 125입니다.

Recurl이 소유한 curl-resolution, spawn, renderer, network-policy, output-processing 오류는 127이며, 완료된 curl transfer의 child exit code는 passthrough 경로에서 그대로 전달합니다.

한계

  • curl 버전을 고정하지 않으므로 설치된 curl이 사용하는 option과 metadata 지원 수준에 따라 결과가 달라질 수 있습니다.
  • Browser renderer는 하나의 HTTP(S) URL과 -L 또는 --location만 지원합니다. 일반 curl option 전체를 browser API로 변환하지 않습니다.
  • Browser renderer는 Chrome/Chromium, CloakBrowser, Camofox server 또는 executable을 자동으로 준비하지 않습니다.
  • non-raw output과 sanitization이 켜진 raw output은 UTF-8 text stdout을 요구합니다. binary 또는 non-UTF-8 response는 변환하지 않습니다.
  • Network policy는 metadata를 포함한 best-effort 검사입니다. 모든 RFC special-use/reserved range를 포괄하는 완전한 egress sandbox가 아니며 browser traffic에도 적용되지 않습니다.
  • Sanitization은 HTML/XSS cleanup이므로 prompt injection, 악성 문서의 의미, 외부 링크의 신뢰성을 판정하지 않습니다.
  • --recurl-renderer-env-pass-through는 credential-bearing environment를 private worker에 전달할 수 있으므로 provider가 요구할 때만 사용해야합니다.

라이센스, 면책 조건

Recurl은 MIT License로 제공되며, AS IS warranty와 liability 조건을 포함합니다.

curl과 모든 third-party library에는 각각의 license가 적용됩니다.

이 project는 개인 사용 목적으로 제작되었으며 기본적으로 연구용으로 제공됩니다.

About

recurl is curl wrapper cli with extra features.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages