urltools-cli

Parse, build, and manipulate URLs from the command line.

Installation

pip install urltools-cli

Features

• Parse URLs into components (scheme, host, port, path, query, fragment)
• Build URLs from individual parts
• Modify query parameters (add, remove, set, clear)
• Join base URLs with paths
• Encode/decode URL components
• Compare two URLs for differences
• Replace specific components
• Normalize URLs (lowercase, remove default ports, sort params)
• Validate URL structure

Usage

Parse URLs

# Full breakdown
urltools parse "https://user:pass@example.com:8080/path?q=1&r=2#section"

# Extract single component
urltools parse "https://api.example.com/v1/users" -c host
# → api.example.com

# Get query params as JSON
urltools parse "https://example.com?foo=bar&baz=qux" -c params --json
# → {"foo": "bar", "baz": "qux"}

Build URLs

# Basic URL
urltools build --host example.com --path /api/v1
# → https://example.com/api/v1

# With port and query params
urltools build -h api.example.com -p 8080 --path /users -q limit=10 -q offset=0
# → https://api.example.com:8080/users?limit=10&offset=0

# With auth
urltools build -h db.local -u admin -w secret -p 5432 --path /mydb
# → https://admin:secret@db.local:5432/mydb

Modify Query Parameters

# Add params
urltools params "https://example.com?a=1" --add b=2 --add c=3
# → https://example.com?a=1&b=2&c=3

# Remove params
urltools params "https://example.com?a=1&b=2&c=3" --remove a --remove c
# → https://example.com?b=2

# Set (replace or add)
urltools params "https://example.com?page=1" --set page=2
# → https://example.com?page=2

# Clear all and start fresh
urltools params "https://example.com?old=junk" --clear --add fresh=value
# → https://example.com?fresh=value

# Output params as JSON
urltools params "https://example.com?a=1&b=2" --json
# → {"a": "1", "b": "2"}

Join URLs

urltools join "https://example.com/api/" "users"
# → https://example.com/api/users

urltools join "https://example.com/api/v1" "/v2/users"
# → https://example.com/v2/users

urltools join "https://example.com/old/path" "../new"
# → https://example.com/new

Encode/Decode

# URL encode
urltools encode "hello world"
# → hello%20world

urltools encode "hello world" --plus
# → hello+world

# URL decode
urltools decode "hello%20world"
# → hello world

# Pipe support
echo "encode this" | urltools encode

Compare URLs

urltools compare "https://a.com/path?x=1" "https://b.com/path?x=2"
# netloc:
#   url1: a.com
#   url2: b.com
# params:
#   x:
#     url1: 1
#     url2: 2

urltools compare "https://a.com" "https://a.com"
# URLs are equivalent

Replace Components

urltools replace "http://example.com/path" --scheme https
# → https://example.com/path

urltools replace "https://old.com/api" --host new.com
# → https://new.com/api

urltools replace "https://example.com:8080/" --port 443
# → https://example.com:443/

Normalize URLs

urltools normalize "HTTP://EXAMPLE.COM:80/Path"
# → http://example.com/Path

urltools normalize "https://example.com:443/api?b=2&a=1"
# → https://example.com/api?a=1&b=2

Validate URLs

urltools validate "https://example.com" && echo "Valid"
# Valid

urltools validate "not-a-url" || echo "Invalid"
# Invalid: Missing scheme

For AI Agents

See SKILL.md for agent-optimized documentation.

License

MIT