nushell-cloudflare

What this skill does

# Nushell Cloudflare Integration

Complete guide for integrating Nushell with Cloudflare services. Covers API access, wrangler CLI integration, and patterns for Workers, R2, KV, D1, Queues, and Durable Objects.

## Authentication

### API Token Setup

```nushell
# Set credentials in environment
$env.CLOUDFLARE_API_TOKEN = "your-api-token"
$env.CLOUDFLARE_ACCOUNT_ID = "your-account-id"

# Or load from file
$env.CLOUDFLARE_API_TOKEN = (open ~/.cloudflare/token | str trim)
```

### API Client Base

```nushell
# Cloudflare API client
def cf-api [
    endpoint: string
    --method: string = "GET"
    --body: any = null
] {
    let base = "https://api.cloudflare.com/client/v4"
    let headers = {
        Authorization: $"Bearer ($env.CLOUDFLARE_API_TOKEN)"
        Content-Type: "application/json"
    }

    let url = $"($base)($endpoint)"

    let response = match $method {
        "GET" => { http get $url -H $headers }
        "POST" => { http post $url $body -H $headers }
        "PUT" => { http put $url $body -H $headers }
        "DELETE" => { http delete $url -H $headers }
    }

    if not $response.success {
        error make {
            msg: $"Cloudflare API error: ($response.errors | to json)"
        }
    }

    $response.result
}
```

## Wrangler CLI Integration

### Setup and Config

```nushell
# Verify wrangler installation
^wrangler --version

# Login (interactive)
^wrangler login

# Check auth status
^wrangler whoami
```

### Worker Management

```nushell
# List workers
def "cf workers list" [] {
    ^wrangler deployments list --json
    | from json
}

# Deploy worker
def "cf workers deploy" [path?: path] {
    let dir = $path | default "."
    cd $dir
    ^wrangler deploy
}

# Tail worker logs
def "cf workers tail" [name: string] {
    ^wrangler tail $name --format json
    | lines
    | each { |line| $line | from json }
}

# View worker details
def "cf workers get" [name: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/workers/scripts/($name)"
}
```

### Worker Development

```nushell
# Start dev server
def "cf workers dev" [--port: int = 8787] {
    ^wrangler dev --port $port
}

# Generate new worker
def "cf workers new" [name: string, --template: string = "hello-world"] {
    ^wrangler init $name --template $template
}
```

## R2 Object Storage

### Bucket Operations

```nushell
# List buckets
def "cf r2 buckets" [] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/r2/buckets"
}

# Create bucket
def "cf r2 create-bucket" [name: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/r2/buckets" --method POST --body {name: $name}
}

# Delete bucket
def "cf r2 delete-bucket" [name: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/r2/buckets/($name)" --method DELETE
}
```

### Object Operations with Wrangler

```nushell
# List objects
def "cf r2 list" [bucket: string, --prefix: string = ""] {
    ^wrangler r2 object list $bucket --prefix $prefix --json
    | from json
}

# Upload file
def "cf r2 put" [bucket: string, key: string, file: path] {
    ^wrangler r2 object put $"($bucket)/($key)" --file $file
}

# Download file
def "cf r2 get" [bucket: string, key: string, --output: path] {
    let out = $output | default $key
    ^wrangler r2 object get $"($bucket)/($key)" --file $out
}

# Delete object
def "cf r2 delete" [bucket: string, key: string] {
    ^wrangler r2 object delete $"($bucket)/($key)"
}
```

### R2 Sync Pattern

```nushell
# Sync local directory to R2
def "cf r2 sync" [local_dir: path, bucket: string, --prefix: string = ""] {
    ls $local_dir | each { |file|
        let key = if $prefix == "" { $file.name } else { $"($prefix)/($file.name)" }
        print $"Uploading: ($file.name) -> ($key)"
        cf r2 put $bucket $key $file.name
    }
}
```

## KV Namespace

### Namespace Management

```nushell
# List namespaces
def "cf kv namespaces" [] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/storage/kv/namespaces"
}

# Create namespace
def "cf kv create-namespace" [title: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/storage/kv/namespaces" --method POST --body {title: $title}
}
```

### Key-Value Operations

```nushell
# Get value
def "cf kv get" [namespace_id: string, key: string] {
    ^wrangler kv key get --namespace-id $namespace_id $key
}

# Put value
def "cf kv put" [namespace_id: string, key: string, value: string] {
    ^wrangler kv key put --namespace-id $namespace_id $key $value
}

# List keys
def "cf kv list" [namespace_id: string, --prefix: string = ""] {
    ^wrangler kv key list --namespace-id $namespace_id --prefix $prefix --json
    | from json
}

# Delete key
def "cf kv delete" [namespace_id: string, key: string] {
    ^wrangler kv key delete --namespace-id $namespace_id $key
}

# Bulk operations
def "cf kv bulk-put" [namespace_id: string, data: list] {
    # data: [{key: "k1", value: "v1"}, {key: "k2", value: "v2"}]
    $data | to json | save --force /tmp/kv-bulk.json
    ^wrangler kv bulk put --namespace-id $namespace_id /tmp/kv-bulk.json
    rm /tmp/kv-bulk.json
}
```

## D1 Database

### Database Management

```nushell
# List databases
def "cf d1 list" [] {
    ^wrangler d1 list --json | from json
}

# Create database
def "cf d1 create" [name: string] {
    ^wrangler d1 create $name --json | from json
}

# Get database info
def "cf d1 info" [name: string] {
    ^wrangler d1 info $name --json | from json
}
```

### Query Operations

```nushell
# Execute SQL
def "cf d1 query" [database: string, sql: string] {
    ^wrangler d1 execute $database --command $sql --json
    | from json
}

# Execute from file
def "cf d1 execute-file" [database: string, file: path] {
    ^wrangler d1 execute $database --file $file --json
    | from json
}

# Migrations
def "cf d1 migrate" [database: string, --dir: path = "./migrations"] {
    ls $dir | sort-by name | each { |f|
        print $"Running migration: ($f.name)"
        cf d1 execute-file $database $f.name
    }
}
```

### D1 Query Builder

```nushell
# Simple query builder
def "cf d1 select" [
    database: string
    table: string
    --columns: list<string> = ["*"]
    --where: string = ""
    --order-by: string = ""
    --limit: int = 100
] {
    let cols = $columns | str join ", "
    mut sql = $"SELECT ($cols) FROM ($table)"

    if $where != "" {
        $sql = $"($sql) WHERE ($where)"
    }
    if $order_by != "" {
        $sql = $"($sql) ORDER BY ($order_by)"
    }
    $sql = $"($sql) LIMIT ($limit)"

    cf d1 query $database $sql
}
```

## Queues

### Queue Management

```nushell
# List queues
def "cf queues list" [] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/queues"
}

# Create queue
def "cf queues create" [name: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/queues" --method POST --body {queue_name: $name}
}

# Delete queue
def "cf queues delete" [name: string] {
    cf-api $"/accounts/($env.CLOUDFLARE_ACCOUNT_ID)/queues/($name)" --method DELETE
}
```

### Message Operations

```nushell
# Send message to queue (via Worker)
def "cf queues send" [queue_binding: string, message: any] {
    # This would typically be done through a Worker binding
    # Here's an example of calling a Worker endpoint that sends to queue
    http post $"https://your-worker.workers.dev/queue/($queue_binding)" $message
}
```

## Durable Objects

Durable Objects require Worker deployment. Here are patterns for managing them:

```nushell
# Create Worker with Durable Object
def "cf do create-worker" [name: string] {
    # Generate wrangler.toml with DO binding
    let config = {
        name: $name
        main: "src/index.ts"
        compatibility_date: (date now | format date "%Y-%m-%d")
        durable_objects: {
            bindings: [
                {name: "MY_DO", class_name: "MyDurableObject"}
            ]
        }
        migrations: [
            {tag: "v1", new_classes: ["MyDurableObject"]}
        ]
    }

    $config | to toml | save wrangler.toml
}
```

## Workflows

### Workflow Pat