urltools-cli 0.1.0
Parse, build, and manipulate URLs from the command line
License: MIT
Requires Python: >=3.8
Keywords: url, cli, parser, query-string, uri

# urltools-cli

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

## Installation

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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

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

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

## For AI Agents

See [SKILL.md](SKILL.md) for agent-optimized documentation.

## License

MIT