Sol

• sol is installed and available in PATH.

Install sol

Choose one of the following methods:

From source (development):

cd ~/work/github/sol
uv sync

From PyPI (when published):

pip install sol

From Git:

pip install git+https://github.com/iodone/sol.git

Core Workflow

1. Discover operations:
   • sol <url> -h
2. Inspect a specific operation:
   • sol <url> <operation> -h
3. Execute with structured input:
   • sol <url> <operation> key=value
   • sol <url> <operation> '<payload-json>'
4. Parse result as JSON envelope:
   • Success: .ok == true, consume .data
   • Failure: .ok == false, inspect .error.code and .error.message
5. For auth-protected endpoints:
   • bearer token: see below
   • API key: see below
   • custom headers: see below

Auth Configuration

Simple Bearer Token

# 1. Set credential
sol auth set my-token --type bearer --secret "your-secret-token"

# 2. Bind to URL
sol auth bind https://api.example.com my-token

# 3. Use automatically
sol https://api.example.com getUser id=123
# Auth headers injected automatically

API Key (Header or Query)

# Header-based
sol auth set my-key --type api_key \
  --secret "your-key" \
  --location header \
  --param-name "X-API-Key"

# Query-based
sol auth set my-key --type api_key \
  --secret "your-key" \
  --location query \
  --param-name "api_key"

sol auth bind https://api.example.com my-key

Custom Headers (Non-Standard Auth)

When APIs use non-standard authentication:

sol auth set my-custom --type custom \
  --header "X-Custom-Token=abc123" \
  --header "X-Workspace-ID=456"

sol auth bind https://api.example.com my-custom

Use custom auth when:

• API doesn't use standard Bearer prefix
• Multiple headers are required
• Auth format is proprietary

Aliases for Short URLs

# Create binding with alias
sol auth bind https://api-prod.example.com my-token --alias prod

# Use short form
sol myapi://prod getUser id=123

# Equivalent to
sol https://api-prod.example.com getUser id=123

Credential Management

# List all credentials
sol auth list

# List all bindings
sol auth bindings

# Remove credential
sol auth remove my-token

# Remove binding
sol auth unbind https://api.example.com

Input Modes

• Preferred (simple payload): key/value
  • sol <url> <operation> field=value
• Bare JSON positional:
  • sol <url> <operation> '{"field":"value"}'

Do not pass raw JSON through --args; use positional JSON.

Output Contract For Reuse

Other skills should treat this skill as the API execution layer and consume only the stable envelope:

• Success fields: ok, kind, protocol, endpoint, operation, data, meta
• Failure fields: ok, error.code, error.message, meta

Default output is JSON. Do not use --text in agent automation paths.

Reuse Rule For Other Skills

• If a skill needs remote API execution, reuse this skill instead of embedding protocol-specific calling logic.
• Upstream skill inputs should be limited to:
  • target URL
  • operation id/name
  • JSON payload
  • required fields to extract from .data

Protocol Detection

Sol automatically detects protocols based on:

1. URL scheme (e.g., https://, custom schemes)
2. Content probing (e.g., fetching OpenAPI spec)
3. Adapter priority (higher priority = tried first)

Built-in adapter:

• OpenAPI: Detects OpenAPI 3.x and Swagger 2.x specs

External adapters (install separately):

• Custom protocol adapters via Python entry points

Cache Management

Sol caches operation results for performance:

# View cache stats
sol cache stats

# Clear cache
sol cache clear

# Disable cache for one call
sol <url> <operation> --no-cache

Troubleshooting

Auth Issues

Problem: "No credential matched for URL"

Solution:

# Check if credential exists
sol auth list

# Check if binding exists
sol auth bindings

# Create binding if missing
sol auth bind <url> <credential-name>

Protocol Detection Fails

Problem: "No adapter can handle this URL"

Solution:

• For OpenAPI: Ensure the URL returns a valid OpenAPI/Swagger spec
• For other protocols: Install the corresponding adapter package
• Check adapter installation: python -c "from sol.framework import Framework; print(Framework().registry.list_adapters())"

URL Normalization Issues

Sol normalizes custom schemes based on bindings:

• myapi://alias → resolved to binding's full URL
• Scheme is inferred from binding (http/https)

If URLs don't resolve:

# Check binding configuration
sol auth bindings | grep <alias>

Reference Files (Load On Demand)

• Common usage patterns and examples:
  • references/usage-patterns.md
• Protocol adapter development guide:
  • See sol-skill-creator skill

See Also

• Sol GitHub repository: https://github.com/iodone/sol
• Architecture docs: docs/architecture.md in repo
• Plugin guide: docs/plugin-guide.md in repo
• OpenAPI adapter source: src/sol/adapters/openapi/adapter.py