IMDS(1)

📦 version 3.4.1, in alpine 3.24

💅 IMDS(1) — general commands manual, but make it metadata ✨

okay so bestie, buckle up — this is imds, from the General Commands Manual section, and it is literally the tool that goes and asks the cloud "who am I??" and brings the answers back. let's get into it 🫶

🌸 NAME 🌸

imds — query instance metadata. that's it, that's the whole vibe: it queries the instance metadata. no cap.

✨ SYNOPSIS ✨

imds [-h|--help] { -e | +e | -E | +E | -A | +A | +n | +s | +t | @alias |
imds-path | -- imds-path ... } ...

🦋 DESCRIPTION 🦋

so imds queries the instance metadata service that your current cloud provider is running. it loads all the cloud-specific metadata conventions from tiny-cloud's provider library, then prints whatever metadata values you asked for straight to standard output. slay.

arguments get processed from left to right, like, in order, okay? and the output control tokens can be mixed right in with your metadata queries in a single invocation — you don't have to do separate runs, which is iconic behavior honestly.

💅 OPTIONS 💅

  • -h, --help — shows a short usage summary and then dips. exit stage left.
  • -e — ignore errors from the metadata queries that come after this. be unbothered.
  • +e — goes back to the default: stop on query errors. back to being responsible 😭
  • -E — hide standard error from the arguments that come after.
  • +E — show standard error from subsequent arguments. heads up: by default only the final request error is shown.
  • -A — hide errors from intermediate request attempts. this is literally the default, it's giving "i don't want to see the mess."
  • +A — show errors from every request attempt. and note: this does not override -E — the standard error controls and the request-attempt controls are independent, they're two separate sliders bestie.
  • +n — write a newline to standard output.
  • +s — write a space to standard output.
  • +t — write a tab to standard output.
  • -- — stop interpreting options, aliases, and output control tokens. every argument after this is treated as a literal provider-specific metadata path. periodt, no more magical thinking ✨

🎀 ALIASES 🎀

  • @hostname — print the instance hostname. main character energy.
  • @local-hostname — print the local hostname.
  • @ssh-keys — print the SSH public keys associated with the instance.
  • @userdata — print instance user data.
  • @nics — print the provider-specific list of network interfaces.
  • @nic:<iface>[,<nic-key> ...] — query metadata for a specific network interface. the interface gets looked up by its local link-layer address first, then one or more NIC-specific keys get resolved. so you point at an interface and it finds it by its MAC, iykyk.

🌈 NIC KEYS 🌈

these are the aliases that get accepted after @nic:<iface> — little sub-aliases, like a group chat inside a group chat:

  • @mac — print the interface MAC address as exposed by the metadata service.
  • @ipv4 — print IPv4 address data for the interface.
  • @ipv6 — print IPv6 address data for the interface.
  • @ipv4-net — print IPv4 subnet information for the interface.
  • @ipv6-net — print IPv6 subnet information for the interface.
  • @ipv4-prefix — print delegated IPv4 prefix information for the interface.
  • @ipv6-prefix — print delegated IPv6 prefix information for the interface.

plus, on top of these aliases, raw provider-specific metadata paths may be used. and the output control tokens -e, +e, +n, +s, and +t are also accepted inside @nic: queries. inclusive king 👑

🧚 ENVIRONMENT 🧚

  • CLOUD — cloud provider name. when it's set to auto, the autodetected provider is used. let the cloud decide, honestly.
  • IMDS_ENDPOINT — single provider metadata endpoint. used as the default value for IMDS_ENDPOINTS.
  • IMDS_ENDPOINTS — whitespace-separated provider metadata endpoint list. heads up bestie: IPv6 endpoints must use brackets, for example [fd00:ec2::254]. don't forget the brackets or it will not go well 😭
  • IMDS_ENDPOINT_WAIT_ATTEMPTS — number of times to check for routes to any IMDS endpoint before trying metadata requests anyway. the default is 10. ten little tries of hope.

🍓 EXIT STATUS 🍓

  • 0 — all requested operations succeeded. we love a happy ending 💖
  • 1 — a query failed and error handling was enabled.
  • 2 — an unknown option was given. unknown option?? not on my watch 💀

🔥 EXAMPLES 🔥

print the instance hostname:

$ imds @hostname

print user data and terminate with a newline:

$ imds @userdata +n

print IPv4 and IPv6 metadata for interface eth1:

$ imds @nic:eth1,@ipv4,@ipv6

query a raw metadata path:

$ imds meta-data/hostname

👑 SEE ALSO 👑

tiny-cloud(8) — go read that one too, it's the whole ecosystem.

fr fr — if something here is dangerous or deprecated, take it seriously. the facts are the facts even when the vibe is immaculate.

that's the whole page babes 💜 this was dated 2026-08-24, and it came out of the General Commands Manual — IMDS(1), and imds itself, wishing you a 0 exit status always. mwah 🎀✨

📦 where this page comes from