cfshare（cfshare 命令行）

CFShare CLI Skill

cfshare wraps Cloudflare Quick Tunnel and outputs structured JSON.

Install when version checks fail

If either command fails, install missing binaries before running any cfshare tool.

cfshare --version
cloudflared --version

1. If cfshare --version fails, install cfshare (requires Node.js and npm):

npm install -g @ystemsrx/cfshare

1. If cloudflared --version fails, install cloudflared by platform:

macOS:

brew install cloudflare/cloudflare/cloudflared

Debian/Ubuntu:

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):

winget install --id Cloudflare.cloudflared

WSL/Linux generic binary install:

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

1. Re-run both version checks. If still failing, stop and report exact stderr output to user.

CLI contract

cfshare <tool> [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 '<json>' or --params-file <path>
• --config '<json>' or --config-file <path>
• --workspace-dir <dir> (only used by expose_files)
• --keep-alive (for expose_*, keep foreground process alive)
• --no-keep-alive (default for expose_*, print result then exit)
• --compact

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

Standard workflow for agents

1. Run env_check first.
2. Create exposure with expose_port or expose_files.
3. Return public_url and expires_at to user immediately.
4. By default, expose_* prints result and exits.
5. Use --keep-alive only when foreground lifecycle control is needed; stop with Ctrl+C when done.

Recommended for stable automation:

• Prefer --params/--params-file over positional raw JSON to reduce quoting errors.
• Prefer access: "token" for sensitive content.
• Treat access: "none" as publicly readable by anyone with link.

Tool usage

1) env_check

cfshare env_check

Returns:

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

2) expose_port

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

Params:

• port: 1..65535
• opts.ttl_seconds
• opts.access: token | basic | none
• opts.protect_origin: default access != "none"
• opts.allowlist_paths: path prefix allowlist for reverse proxy

Returns:

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

3) expose_files

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

Params:

• paths: files/directories to copy into temp workspace
• opts.mode: normal | zip (default normal)
• opts.presentation: download | preview | raw (default download)
• opts.ttl_seconds
• opts.access: token | basic | none
• opts.max_downloads: auto-stop after threshold

File Serving Behavior:

Mode: normal

• Single file → served directly at the root URL.
• Multiple files or a directory → displayed in an intuitive file explorer interface.

Mode: zip

• All files are packaged into a ZIP archive.

Presentation:

• Default behaviors: download | preview | raw
• Behavior can be overridden via query parameters.

- download → forces browser file save. - preview → renders inline (images, PDF, Markdown, audio/video, HTML, text, etc.). - raw → serves original content without any wrapper.

• If a file type is not previewable, preview automatically falls back to raw, then to download.

Returns:

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

4) exposure_list

cfshare exposure_list

Lists tracked sessions with id/type/status/public_url/local_url/expires_at.

5) exposure_get

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

cfshare exposure_stop --params '{"id":"all"}'

Stops tunnel/proxy/origin and removes temporary workspace. Returns {stopped, failed, cleaned}.

7) exposure_logs

cfshare exposure_logs --params '{"id":"files_xxx","opts":{"component":"all","lines":200}}'

component: tunnel | origin | all.

8) maintenance

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 or opts.ignore_patterns)

9) audit_query

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

10) audit_export

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 in CLI mode

• expose_port and expose_files exit by default after printing result; use --keep-alive to hold foreground.
• Current session registry is in-process memory; separate cfshare invocations do not restore full live session state.
• basic mode credentials are masked in outputs, so token is usually the practical authenticated mode for agent-delivered links.

Troubleshooting

• cloudflared binary not found: install cloudflared or set --config '{"cloudflaredPath":"..."}'
• local service is not reachable on 127.0.0.1:<port>: start service first
• path blocked by ignore policy: adjust policy.ignore or maintenance set_policy
• port blocked by policy: update blockedPorts in policy if intentional

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