| .agents/skills | ||
| app | ||
| docs/plans | ||
| scripts | ||
| src/opengraph | ||
| static | ||
| templates | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| agents.md | ||
| AGENTS.md | ||
| Dockerfile | ||
| Justfile | ||
| llms-full.txt | ||
| llms.txt | ||
| ogcli | ||
| opengraph.py | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
| skill.md | ||
| uv.lock | ||
OpenGraph Analyzer
Install reproducibly with uv sync, then run uv run ogcli URL.
The CLI prints a colorized summary table on interactive terminals. Use
-f/--format with json, yaml, toon, or table; --color and
--no-color control color in the table output. Results and structured output
go to stdout. JSON is syntax-highlighted when color is enabled. Errors go to
stderr.
uv run ogcli https://example.com/ --format json
uv run ogcli https://example.com/ -f yaml --no-color
uv run ogcli issues https://example.com/
The web deployment entrypoint is opengraph.web:app (or uv run uvicorn opengraph.web:app --app-dir src).
app/opengraph.py is retained only as a compatibility forwarder.
Agent API
Agents can discover the production API at /agents.md, /AGENTS.md, /llms.txt,
/llms-full.txt, /skill.md, and /index.md. The homepage also returns Markdown
when requested with Accept: text/markdown. The OpenAPI schema is served at /openapi.json.
Use POST /api/v1/analyze with {"url":"https://example.com/"}; see the full
contract in llms-full.txt. The API analyzes server-rendered HTML and blocks
private or reserved network addresses.
Run just check before building or deploying. It verifies the frozen uv lock,
tests with an 80% coverage floor, Ruff lint and formatting, and strict ty checks
across the web adapter, package, and tests.
Containers
The default image is registry.wayl.one/opengraph:latest.
just dev
just build # Podman build with registry-backed layer cache
just push
just release
For Docker with Buildx, use just docker-build or just docker-release.
The recipe creates a dedicated docker-container Buildx builder when needed so
registry cache export works with standard Docker installations.
Override IMAGE and TAG when needed:
IMAGE=registry.wayl.one/opengraph TAG=1.0.0 just release
The deployed version is read from the neighboring homelab-argo checkout.
Bump the patch version, then publish it:
just bump-image
just publish-image
publish-image builds and pushes the image, commits and pushes the GitOps
manifest, refreshes Argo, waits for the rollout, and checks the public health
endpoint. If bump-image was skipped, it warns that the same version is
already deployed and that no rollout will occur. Set HOMELAB_REPO when the
GitOps checkout is in another location:
HOMELAB_REPO=/path/to/homelab-argo just bump-image
HOMELAB_REPO=/path/to/homelab-argo just publish-image