URL Shortener CLI

Shorten URLs from terminal with custom slugs, local storage, and basic analytics. A self‑contained CLI that maps long URLs to short slugs using a local JSON...

Security Scan

The skill is internally consistent: a local Python CLI that reads/writes ~/.url-shortener/mappings.json with no external network calls or credentials required.

Purpose & Capability

The name and description (local URL shortener, local JSON storage, basic analytics) match the code and SKILL.md. The only required binary is python3, which is appropriate for a Python CLI. There are no requested credentials or unrelated dependencies.

Instruction Scope

SKILL.md directs the agent/user to run the included scripts/main.py and documents CLI commands; instructions reference only the local config directory (~/.url-shortener) and JSON files. There are no instructions to read unrelated system files, access network endpoints, or exfiltrate data.

Install Mechanism

There is no install spec (instruction-only), and the provided code is a self-contained Python script with no external package downloads. No network-based installers or archive extraction mechanisms are used.

Credentials

The skill requests no environment variables or credentials. The code operates entirely on local files under the user's home directory and does not access other services or secrets.

Persistence & Privilege

always is false and the skill does not request any elevated or persistent platform privileges. It creates and uses only its own config directory (~/.url-shortener) and does not modify other skills or global agent settings.

Assessment

This tool appears local and coherent with its description, but note that all mappings are stored unencrypted in ~/.url-shortener/mappings.json and accessible to any account with access to your user files. Before installing, review file permissions for that directory, back up/export if you need persistence across machines, and be aware that shortened URLs are only usable on your machine (this is not a public hosting service). If you want to be extra cautious, inspect the full scripts/main.py file yourself (no network calls were found in the provided code) and run the CLI from a non-privileged user account.

What This Does

A local, self‑contained URL shortener that runs entirely on your machine. No external APIs, no internet required after setup.

Key features:

• Shorten URLs – Generate short slugs for long URLs
• Custom slugs – Use your own short codes
• Expand slugs – Retrieve original URLs
• Local storage – All mappings saved in a JSON file (~/.url-shortener/mappings.json)
• Basic analytics – Track click counts and creation dates
• Management – List, search, update, and delete mappings
• Import/export – Backup and restore your URL database

How To Use

Shorten a URL:

./scripts/main.py shorten https://example.com/very/long/path

Shorten with custom slug:

./scripts/main.py shorten https://example.com --slug mypage

Expand a slug:

./scripts/main.py expand mypage

List all mappings:

./scripts/main.py list

Get detailed info for a slug:

./scripts/main.py info mypage

Delete a mapping:

./scripts/main.py delete mypage

Search URLs:

./scripts/main.py search "example"

Import/export:

./scripts/main.py export --file urls.json
./scripts/main.py import --file urls.json

Full command reference:

./scripts/main.py help

Commands

• shorten: Create a new short URL

  • url: The long URL to shorten (required)
  • --slug: Custom slug (optional, auto‑generated if omitted)
  • --description: Optional description
  • --tags: Comma‑separated tags for organization

• expand: Get the original URL for a slug

  • slug: The short slug (required)

• list: List all mappings

  • --sort: Sort by created, clicks, slug, url (default: created)
  • --reverse: Reverse sort order
  • --limit: Show only N entries
  • --json: Output as JSON

• info: Show detailed information for a slug

  • slug: The short slug (required)
  • --json: Output as JSON

• delete: Delete a mapping

  • slug: The short slug to delete (required)
  • --force: Skip confirmation

• search: Search in URLs, descriptions, or tags

  • query: Search term (required)
  • --field: Search field: url, description, tags, all (default: all)

• export: Export mappings to a JSON file

  • --file: Output file (default: urls-export.json)

• import: Import mappings from a JSON file

  • --file: Input file (required)
  • --overwrite: Replace existing mappings (default: merge)

• stats: Show usage statistics

  • --json: Output as JSON

• cleanup: Remove old or unused mappings

  • --older-than-days: Remove entries older than N days
  • --max-clicks: Remove entries with fewer than N clicks
  • --dry-run: Show what would be removed

Output Examples

Shorten a URL:

$ ./scripts/main.py shorten https://github.com/openclaw/openclaw
Shortened: https://github.com/openclaw/openclaw
Slug:      x7f9k2
Full command: ./scripts/main.py expand x7f9k2

List mappings:

Slug     URL                                     Clicks  Created
-------  --------------------------------------  ------  -------------------
x7f9k2   https://github.com/openclaw/openclaw    12      2026‑03‑18 10:30:00
mypage   https://example.com                     5       2026‑03‑17 14:22:00
docs     https://docs.openclaw.ai                42      2026‑03‑16 09:15:00

JSON output (with --json):

{
  "x7f9k2": {
    "url": "https://github.com/openclaw/openclaw",
    "slug": "x7f9k2",
    "clicks": 12,
    "created": "2026-03-18T10:30:00Z",
    "description": "OpenClaw GitHub repo",
    "tags": ["github", "openclaw"]
  }
}

Installation Notes

Requires Python 3.6+. No external dependencies. The tool creates a configuration directory at ~/.url-shortener/ and stores mappings in mappings.json.

Limitations

• Local only – Mappings exist only on your machine; not shareable across devices
• No public access – Shortened URLs only work on your own system
• No expiration – Entries persist until manually deleted
• No collision detection – Custom slugs must be unique (tool will warn)
• Basic analytics – Only tracks click counts; no geographic or referrer data
• No QR codes – Does not generate QR codes for shortened URLs
• No API – Cannot be called by other applications (except via CLI)

Security Considerations

• All data stored locally in plain JSON (no encryption)
• No authentication required (any user on the system can access)
• URLs are not validated for safety (may point to malicious sites)
• No rate limiting or abuse protection
• File permissions follow your user's default

Examples

Create a short link for documentation:

./scripts/main.py shorten https://docs.openclaw.ai --slug docs --description "OpenClaw documentation"

Get the most‑clicked links:

./scripts/main.py list --sort clicks --reverse --limit 5

Search for GitHub links:

./scripts/main.py search "github" --field url

Backup your URL database:

./scripts/main.py export --file url-backup-$(date +%Y%m%d).json

Clean up old entries (older than 30 days):

./scripts/main.py cleanup --older-than-days 30