# CLI

## Table of Contents

- [Authentication](#authentication)
- [Coding agents](#coding-agents)
- [Headers](#headers)
- [Structured input](#structured-input)
- [Tracing](#tracing)
- [Endpoint](#endpoint)

---

Installing [microlink.io](https://www.npmjs.com/package/microlink.io) also ships a `microlink` binary where every product is a subcommand. Flags map one-to-one to the [options](https://microlink.io/docs/sdk/getting-started/options) each method accepts:

```bash
npminstall-gmicrolink.io
```

```bash
microlinkhttps://example.com

microlinkmarkdownhttps://example.com

microlinkscreenshothttps://example.com--fullPage

microlinklogohttps://github.com--square

microlinklinkshttps://example.com

microlinksearch"best coffee"--limit10--locationes
```

Passing a URL with no product returns [metadata](https://microlink.io/docs/sdk/methods/metadata). Strings print raw; objects pretty-print as JSON, so the output is pipe-friendly. Every subcommand except `search` runs on the free tier without credentials.

Print the markdown reference for any product with `docs`:

```bash
microlinkextractdocs

microlinkscreenshotdocs
```

Run `microlink --help` for the list of products, or `microlink <product> --help` for the flags a product accepts. You can also try it without installing anything:

```bash
npxmicrolink.ioscreenshothttps://example.com--fullPage
```

## Authentication

Every [Microlink account](https://dashboard.microlink.io/signup?from=/docs/sdk/getting-started/cli&cta=docs:content) gets a free API key. The `search` product needs it, and any other product uses it to apply your account quota; a [paid plan](https://microlink.io/pricing) adds volume. The CLI resolves it, in this order, from the `--api-key` flag, the `MICROLINK_API_KEY` environment variable, or the key saved by `microlink login`:

```bash
microlinksearch"web performance"--api-keyYOUR_KEY
```

```bash
exportMICROLINK_API_KEY=YOUR_KEY

microlinkscreenshothttps://example.com
```

```bash
microlinklogin
```

`login` opens your [dashboard](https://dashboard.microlink.io/login?from=/docs/sdk/getting-started/cli&cta=docs:content) in the browser, lets you pick one of your API keys, and saves it under `~/.config/microlink/config.json` with owner-only permissions. `microlink logout` removes it.

## Coding agents

`microlink setup` detects the coding agents on this machine and installs the [Microlink skill](https://microlink.io/skills/microlink) for them. When it finishes, type `/microlink` in the agent to start.

```bash
microlinksetup
```

## Headers

Forward headers to the target page with `--header` (or `-H`), repeatable:

```bash
microlinkmarkdownhttps://example.com--header'Cookie: auth_token=…'
```

Headers meant for the API request itself, rather than the target page, take the `--http.header.<name>` form:

```bash
microlinkpdfhttps://example.com--http.header.authorization'Bearer …'
```

## Structured input

Commands that take structured arguments accept inline JSON. [extract](https://microlink.io/docs/sdk/methods/extract) reads its rules from `--data`, and [function](https://microlink.io/docs/sdk/methods/function) reads its code from a file:

```bash
microlinkextracthttps://microlink.io--data'{"image":{"selector":"meta[property=og:image]","attr":"content","type":"image"}}'

microlinkfunctionhttps://example.com--file./fn.js
```

Any extra flag passed to `function` is forwarded to the function as a named argument, the same way [custom parameters](https://microlink.io/docs/sdk/methods/function#custom-parameters) work in the SDK.

Object-shaped options such as `--viewport`, `--overlay`, or `--margin` take JSON too:

```bash
microlinkscreenshothttps://example.com--viewport'{"width":1280,"height":800}'
```

## Tracing

Add `--trace` to print the exact API request and response instead of the result, with the API key masked. `--trace-full` prints the key in clear:

```bash
microlinkscreenshothttps://example.com--fullPage--trace
```

Every successful call also prints a footer to stderr with the response size, timing, cache status, and `x-request-id`, so stdout stays clean for piping.

`--trace` is not available for `search` and `function`, which use their own transports.

## Endpoint

Point the CLI at a different API deployment with `--endpoint`, mirroring the client-level [option](https://microlink.io/docs/sdk/getting-started/options#client-level-defaults) of the same name:

```bash
microlinkmetadatahttps://example.com--endpointhttps://microlink.internal.example.com
```

See the [CLI](https://microlink.io/integrations/cli) page for a walkthrough.