CLI Tool

Installation

The CLI tool is installed alongside the Python SDK:

pip install surflet

Once installed, the surflet command is available.

Configuration

Configure your API connection via environment variables:

export SURFLET_API_KEY=sk_live_...
export SURFLET_API_URL=https://api.surflet.app

For local development:

export SURFLET_API_KEY=sk_test_surflet123
export SURFLET_API_URL=http://localhost:3001

Command Reference

publish — Publish a Page

# Simple publish
surflet publish --title "Deploy Report" --content "Build #456 deployed successfully"

# Publish from a file
surflet publish --title "Analysis Report" --file ./report.md

# Specify type and notification
surflet publish \
  --title "Refund Approval" \
  --type approval \
  --content "Please review the refund request" \
  --notify "slack:#cs-approvals"

# Publish from a JSON payload
surflet publish --payload ./approval-payload.json

Parameters:

Parameter	Description	Required
--title	Page title	Yes
--content	Markdown content	One of --file/--payload
--file	Read content from a Markdown file	One of --content/--payload
--payload	Read the full payload from a JSON file	One of --content/--file
--type	Page type (briefing/approval/review/form/dashboard)	No
--notify	Notification channel (e.g. slack:#channel)	No
--access	Access mode (public/authenticated)	No
--json	Output result as JSON	No

inbox — View Inbox

# View all pending items
surflet inbox

# Filter by status
surflet inbox --status pending
surflet inbox --status completed

# Pagination
surflet inbox --page 2 --per-page 20

# JSON output
surflet inbox --json

Parameters:

Parameter	Description	Default
--status	Filter by status (pending/completed/all)	all
--page	Page number	1
--per-page	Items per page	10
--json	JSON output	No

approve — Approve

surflet approve pg_xxx --comment "Looks good"

Parameters:

Parameter	Description	Required
page_id	Page ID (positional argument)	Yes
--comment	Approval comment	No

reject — Reject

surflet reject pg_xxx --comment "Need more details about the damage"

Parameters:

Parameter	Description	Required
page_id	Page ID (positional argument)	Yes
--comment	Rejection reason	No (but recommended)

get — View a Page

# View page details
surflet get pg_xxx

# JSON output
surflet get pg_xxx --json

revoke — Revoke a Page

surflet revoke pg_xxx

status — View Approval Status

surflet status pg_xxx

Outputs the current state of the approval chain, including the approvers, status, and timestamp for each step.

Piping and Script Integration

The CLI supports --json output for easy integration with other tools:

# Publish and extract the URL
PAGE_URL=$(surflet publish --title "Report" --content "..." --json | jq -r '.pageUrl')
echo "Published: $PAGE_URL"

# Batch-check pending items
surflet inbox --status pending --json | jq '.items[] | .title'

# Use in CI/CD
surflet publish \
  --title "Deploy Approval: $CI_COMMIT_SHA" \
  --type approval \
  --file ./deploy-summary.md \
  --notify "slack:#deploys" \
  --json

Exit Codes

Exit Code	Meaning
0	Success
1	General error
2	Authentication failed (invalid API Key)
3	Page not found
4	Insufficient permissions