📦 CF Share — CF工具

# CFShare CLI Skill cfshare wraps Cloudflare Quick Tunnel and outputs structured JSON.

Install 当...时 version checks 失败

If either command fails, install missing binaries before running any cfshare tool. ``bash cfshare --version cloudflared --version `

• 如果 cfshare --version fails, install cfshare (requires 节点.js 和 npm):

`bash npm install -g @ystemsrx/cfshare `

• 如果 cloudflared --version fails, install cloudflared 由 platform:

macOS: `bash brew install cloudflare/cloudflare/cloudflared ` Debian/Ubuntu: `bash curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list sudo apt-get update && sudo apt-get install -y cloudflared ` Windows (PowerShell): `powershell winget install --id Cloudflare.cloudflared ` WSL/Linux generic binary install: `bash curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared sudo chmod +x /usr/local/bin/cloudflared `

• Re-run both version checks. 如果 仍然 failing, 停止 和 举报 exact stderr 输出 到 用户.

CLI contract

`bash cfshare [params-json] [options] ` Supported tools:

• env_check
• expose_port
• expose_files
• exposure_list
• exposure_get
• exposure_stop
• exposure_logs
• maintenance
• audit_query
• audit_export

Global options:

• --params '' 或 --params-file
• --配置 '' 或 --配置-file
• --workspace-dir (仅 used 由 expose_files)
• --keep-alive (对于 expose_, keep foreground process alive)
• --否-keep-alive (默认 对于 expose_, 打印 结果 然后 exit)
• --compact

Command names accept _ and - (for example expose-port == expose_port).

Standard workflow 对于 agents

• Run env_check 第一个.
• 创建 exposure 带有 expose_port 或 expose_files.
• Return public_url 和 expires_at 到 用户 immediately.
• 由 默认, expose_ prints 结果 和 exits.
• 使用 --keep-alive 仅 当...时 foreground lifecycle control needed; 停止 带有 Ctrl+C 当...时 已完成.

Recommended for stable automation:

• Prefer --params/--params-file 在...上 positional raw JSON 到 归约 quoting errors.
• Prefer access: "令牌" 对于 sensitive content.
• Treat access: "无" 作为 publicly readable 由 anyone 带有 链接.

Tool usage

1) env_check

`bash cfshare env_check ` Returns:

• cloudflared.ok/path/version
• defaults (effective policy + runtime paths)
• warnings

2) expose_port

`bash cfshare expose_port --params '{"port":3000,"opts":{"access":"token","ttl_seconds":3600}}' ` Params:

• port: 1..65535
• opts.ttl_seconds
• opts.access: 令牌 | basic | 无
• opts.protect_origin: 默认 access != "无"
• opts.allowlist_paths: path prefix allowlist 对于 reverse proxy

Returns:

• id
• public_url (令牌 mode auto-appends ?令牌=...)
• local_url
• expires_at
• access_info (secrets masked)

3) expose_files

`bash cfshare expose_files --params '{"paths":["./dist"],"opts":{"mode":"normal","presentation":"preview","access":"none"}}' ` Params:

• paths: files/directories 到 复制 进入 temp workspace
• opts.mode: normal | zip (默认 normal)
• opts.presentation: 下载 | 预览 | raw (默认 下载)
• opts.ttl_seconds
• opts.access: 令牌 | basic | 无
• opts.max_downloads: auto-停止 之后 threshold

File Serving Behavior: Mode: normal

• Single file → served directly 在 root URL.
• Multiple files 或 directory → displayed 在...中 intuitive file explorer 接口.

Mode: zip

• 所有 files packaged 进入 ZIP 归档.

Presentation:

• 默认 behaviors: 下载 | 预览 | raw
• Behavior 可以 overridden 通过 查询 parameters.

- 下载 → forces browser file 保存. - 预览 → renders inline (images, PDF, Markdown, audio/video, HTML, text, etc.). - raw → serves original content 没有 任何 wrapper.

• 如果 file 类型 不 previewable, 预览 automatically falls back 到 raw, 然后 到 下载.

Returns:

• id, public_url, expires_at, mode, presentation
• manifest, manifest_mode, manifest_meta

4) exposure_list

`bash cfshare exposure_list ` Lists tracked sessions with id/type/status/public_url/local_url/expires_at.

5) exposure_get

`bash cfshare exposure_get --params '{"id":"port_xxx","opts":{"probe_public":true}}' cfshare exposure_get --params '{"filter":{"status":"running"},"fields":["id","status","public_url"]}' ` Supports selector by id, ids, or filter. Can probe public reachability via opts.probe_public.

6) exposure_stop

`bash cfshare exposure_stop --params '{"id":"all"}' ` Stops tunnel/proxy/origin and removes temporary workspace. Returns {stopped, failed, cleaned}.

7) exposure_logs

`bash cfshare exposure_logs --params '{"id":"files_xxx","opts":{"component":"all","lines":200}}' ` component: tunnel | origin | all.

8) maintenance

`bash cfshare maintenance --params '{"action":"run_gc"}' cfshare maintenance --params '{"action":"set_policy","opts":{"policy":{"maxTtlSeconds":7200},"ignore_patterns":[".pem",".env*"]}}' ` Actions:

• start_guard
• run_gc
• set_policy (requires opts.policy 或 opts.ignore_patterns)

9) audit_query

`bash cfshare audit_query --params '{"filters":{"event":"exposure_started","limit":100}}' `

10) audit_export

`bash cfshare audit_export --params '{"range":{"from_ts":"2026-01-01T00:00:00Z","output_path":"./audit.jsonl"}}' `

Runtime files (CLI mode)

Default CLI state directory is ~/.cfshare:

• policy.json
• policy.ignore
• audit.jsonl
• sessions.json
• workspaces/
• exports/

Important limitations 在...中 CLI mode

• expose_port 和 expose_files exit 由 默认 之后 printing 结果; 使用 --keep-alive 到 hold foreground.
• Current 会话 registry 在...中-process memory; separate cfshare invocations 做 不 恢复 满 live 会话 state.
• basic mode credentials masked 在...中 outputs, 所以 令牌 usually practical authenticated mode 对于 agent-delivered links.

Troubleshooting

• cloudflared binary 不 found: install cloudflared 或 设置 --配置 '{"cloudflaredPath":"..."}'
• local 服务 不 reachable 在...上 127.0.0.1:: 开始 服务 第一个
• path blocked 由 ignore policy: adjust policy.ignore 或 maintenance set_policy
• port blocked 由 policy: 更新 blockedPorts 在...中 policy 如果 intentional

Use CFSHARE_LOG_LEVEL=info or CFSHARE_LOG_LEVEL=debug` for more stderr logs.