# @ref <id>: run a dependency automatically when its captured value is missing #35

Why

Today apic run whoami before apic run login fails with a helpful error ("it is captured by request login; run apic run login first"). httpyac's # @ref goes one step further and runs the dependency for you. For an agent issuing one command at a time this removes a whole round trip, and for a human it removes the one thing everyone forgets. It stays declarative: a name, not a script.

What

### Who am I
# @name whoami
# @ref login
GET {{baseUrl}}/me
Authorization: Bearer {{token}}

Acceptance criteria:

• # @ref <id> (repeatable) names a request in the project. Before sending, if any variable the request needs is missing and a referenced request captures it, apic runs that request first, then continues. A referenced request whose captures are all present is skipped.
• # @forceRef <id> always runs the reference first (httpyac spelling, for the case where a token must be fresh).
• Applies uniformly to apic run, flows, the UI (enter on whoami runs login then whoami, both rows update), MCP run_request and the BDD I run step. A reference runs at most once per invocation. Cycles are a validation error naming the chain.
• Output: run prints the referenced request's result first as it does for a flow; --json emits one object per request actually sent. describe gains "refs": ["login"] and list --json gains refs.
• apic validate errors on a @ref to an unknown request.
• The existing "run login first" hint stays for requests without @ref.

Where

• internal/httpfile/parse.go (KnownDirectives), ast.go
• internal/project/project.go (request lookup; captured-by index used by the missing-variable hint)
• internal/runner/runner.go (Run, RunAll), internal/ui/run.go, internal/mcp/server.go, internal/bdd/steps.go

Docs

docs/format.md (Directives table), docs/cheatsheet.md, docs/cookbook.md ("Log in once" recipe gains the @ref variant), docs/agents.md, docs/cli.md (describe JSON).

Tests

Runner tests: missing capture triggers the ref; present capture skips it; forceRef always runs; cycle detection; --json object count. A UI test through Update/View; a BDD scenario in internal/bdd/bdd_test.go; a validate test.