\r \r

CFShare CLI Skill\r

\r cfshare wraps Cloudflare Quick Tunnel and outputs structured JSON.\r \r

Install when version checks fail\r

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

cfshare --version\r
cloudflared --version\r
```\r
\r
1. If `cfshare --version` fails, install `cfshare` (requires Node.js and npm):\r
\r
```bash\r
npm install -g @ystemsrx/cfshare\r
```\r
\r
2. If `cloudflared --version` fails, install `cloudflared` by platform:\r
\r
macOS:\r
\r
```bash\r
brew install cloudflare/cloudflare/cloudflared\r
```\r
\r
Debian/Ubuntu:\r
\r
```bash\r
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null\r
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\r
sudo apt-get update && sudo apt-get install -y cloudflared\r
```\r
\r
Windows (PowerShell):\r
\r
```powershell\r
winget install --id Cloudflare.cloudflared\r
```\r
\r
WSL/Linux generic binary install:\r
\r
```bash\r
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared\r
sudo chmod +x /usr/local/bin/cloudflared\r
```\r
\r
3. Re-run both version checks. If still failing, stop and report exact stderr output to user.\r
\r
## CLI contract\r
\r
```bash\r
cfshare \x3Ctool> [params-json] [options]\r
```\r
\r
Supported tools:\r
\r
- `env_check`\r
- `expose_port`\r
- `expose_files`\r
- `exposure_list`\r
- `exposure_get`\r
- `exposure_stop`\r
- `exposure_logs`\r
- `maintenance`\r
- `audit_query`\r
- `audit_export`\r
\r
Global options:\r
\r
- `--params '\x3Cjson>'` or `--params-file \x3Cpath>`\r
- `--config '\x3Cjson>'` or `--config-file \x3Cpath>`\r
- `--workspace-dir \x3Cdir>` (only used by `expose_files`)\r
- `--keep-alive` (for `expose_*`, keep foreground process alive)\r
- `--no-keep-alive` (default for `expose_*`, print result then exit)\r
- `--compact`\r
\r
Command names accept `_` and `-` (for example `expose-port` == `expose_port`).\r
\r
## Standard workflow for agents\r
\r
1. Run `env_check` first.\r
2. Create exposure with `expose_port` or `expose_files`.\r
3. Return `public_url` and `expires_at` to user immediately.\r
4. By default, `expose_*` prints result and exits.\r
5. Use `--keep-alive` only when foreground lifecycle control is needed; stop with `Ctrl+C` when done.\r
\r
Recommended for stable automation:\r
\r
- Prefer `--params`/`--params-file` over positional raw JSON to reduce quoting errors.\r
- Prefer `access: "token"` for sensitive content.\r
- Treat `access: "none"` as publicly readable by anyone with link.\r
\r
## Tool usage\r
\r
### 1) env_check\r
\r
```bash\r
cfshare env_check\r
```\r
\r
Returns:\r
\r
- `cloudflared.ok/path/version`\r
- `defaults` (effective policy + runtime paths)\r
- `warnings`\r
\r
### 2) expose_port\r
\r
```bash\r
cfshare expose_port --params '{"port":3000,"opts":{"access":"token","ttl_seconds":3600}}'\r
```\r
\r
Params:\r
\r
- `port`: `1..65535`\r
- `opts.ttl_seconds`\r
- `opts.access`: `token | basic | none`\r
- `opts.protect_origin`: default `access != "none"`\r
- `opts.allowlist_paths`: path prefix allowlist for reverse proxy\r
\r
Returns:\r
\r
- `id`\r
- `public_url` (token mode auto-appends `?token=...`)\r
- `local_url`\r
- `expires_at`\r
- `access_info` (secrets are masked)\r
\r
### 3) expose_files\r
\r
```bash\r
cfshare expose_files --params '{"paths":["./dist"],"opts":{"mode":"normal","presentation":"preview","access":"none"}}'\r
```\r
\r
Params:\r
\r
- `paths`: files/directories to copy into temp workspace\r
- `opts.mode`: `normal | zip` (default `normal`)\r
- `opts.presentation`: `download | preview | raw` (default `download`)\r
- `opts.ttl_seconds`\r
- `opts.access`: `token | basic | none`\r
- `opts.max_downloads`: auto-stop after threshold\r
\r
File Serving Behavior:\r
\r
Mode: normal\r
\r
- Single file → served directly at the root URL.\r
- Multiple files or a directory → displayed in an intuitive file explorer interface.\r
\r
Mode: zip\r
\r
- All files are packaged into a ZIP archive.\r
\r
Presentation:\r
\r
- Default behaviors: download | preview | raw\r
- Behavior can be overridden via query parameters.\r
  - download → forces browser file save.\r
  - preview → renders inline (images, PDF, Markdown, audio/video, HTML, text, etc.).\r
  - raw → serves original content without any wrapper.\r
- If a file type is not previewable, preview automatically falls back to raw, then to download.\r
\r
Returns:\r
\r
- `id`, `public_url`, `expires_at`, `mode`, `presentation`\r
- `manifest`, `manifest_mode`, `manifest_meta`\r
\r
### 4) exposure_list\r
\r
```bash\r
cfshare exposure_list\r
```\r
\r
Lists tracked sessions with `id/type/status/public_url/local_url/expires_at`.\r
\r
### 5) exposure_get\r
\r
```bash\r
cfshare exposure_get --params '{"id":"port_xxx","opts":{"probe_public":true}}'\r
cfshare exposure_get --params '{"filter":{"status":"running"},"fields":["id","status","public_url"]}'\r
```\r
\r
Supports selector by `id`, `ids`, or `filter`.\r
Can probe public reachability via `opts.probe_public`.\r
\r
### 6) exposure_stop\r
\r
```bash\r
cfshare exposure_stop --params '{"id":"all"}'\r
```\r
\r
Stops tunnel/proxy/origin and removes temporary workspace.\r
Returns `{stopped, failed, cleaned}`.\r
\r
### 7) exposure_logs\r
\r
```bash\r
cfshare exposure_logs --params '{"id":"files_xxx","opts":{"component":"all","lines":200}}'\r
```\r
\r
`component`: `tunnel | origin | all`.\r
\r
### 8) maintenance\r
\r
```bash\r
cfshare maintenance --params '{"action":"run_gc"}'\r
cfshare maintenance --params '{"action":"set_policy","opts":{"policy":{"maxTtlSeconds":7200},"ignore_patterns":["*.pem",".env*"]}}'\r
```\r
\r
Actions:\r
\r
- `start_guard`\r
- `run_gc`\r
- `set_policy` (requires `opts.policy` or `opts.ignore_patterns`)\r
\r
### 9) audit_query\r
\r
```bash\r
cfshare audit_query --params '{"filters":{"event":"exposure_started","limit":100}}'\r
```\r
\r
### 10) audit_export\r
\r
```bash\r
cfshare audit_export --params '{"range":{"from_ts":"2026-01-01T00:00:00Z","output_path":"./audit.jsonl"}}'\r
```\r
\r
## Runtime files (CLI mode)\r
\r
Default CLI state directory is `~/.cfshare`:\r
\r
- `policy.json`\r
- `policy.ignore`\r
- `audit.jsonl`\r
- `sessions.json`\r
- `workspaces/`\r
- `exports/`\r
\r
## Important limitations in CLI mode\r
\r
- `expose_port` and `expose_files` exit by default after printing result; use `--keep-alive` to hold foreground.\r
- Current session registry is in-process memory; separate `cfshare` invocations do not restore full live session state.\r
- `basic` mode credentials are masked in outputs, so `token` is usually the practical authenticated mode for agent-delivered links.\r
\r
## Troubleshooting\r
\r
- `cloudflared binary not found`: install `cloudflared` or set `--config '{"cloudflaredPath":"..."}'`\r
- `local service is not reachable on 127.0.0.1:\x3Cport>`: start service first\r
- `path blocked by ignore policy`: adjust `policy.ignore` or `maintenance set_policy`\r
- `port blocked by policy`: update `blockedPorts` in policy if intentional\r
\r
Use `CFSHARE_LOG_LEVEL=info` or `CFSHARE_LOG_LEVEL=debug` for more stderr logs.\r