docs/reference/diagnostics/consumers/iquery.md

# iquery

`iquery` - the Fuchsia Inspect API Query Toolkit

## Synopsis

```
iquery [--format <format>] <command> [<args>]
```

## Description

`iquery` is a utility program for inspecting component nodes exposed over the
[Inspect API]. It accepts a set of options and a command with
its respective options.

## Options

### `--format`

The format in which the output will be displayed.

Accepted formats:

- `text`: default, good for human reading
- `json`: good for machine reading

### `--help`

Prints usage information.

## Commands

### `list`

Lists all components (relative to the scope where the archivist receives events
from) of components that expose inspect.

For v1: this is the realm path plus the realm name.

For v2: this is the moniker without the instances ids.

Example usage:

```
$ iquery list
archivist.cmx
bootstrap/device_manager
...
```

#### `--manifest`

The name that you specified for the manifest file. If this is specified, the
output only contains monikers for components whose URL contains the specified
name.

#### `--with-url`

Prints both the moniker and the URL with which the component was launched.

#### `--help`

Prints usage information about `list`.

### `list-files [<paths...>]`

Lists all files which contain inspect data under the given `paths`. This will
only list files for v1 components given that v2 components are not mapped to the
filesystem at the moment.

The files that this command looks for are:

- `fuchsia.inspect.Tree`: A service file. The standard way inspect libraries
  export inspect data.
- `*.inspect`: VMO files with inspect data. The standard way the Dart inspect
  library exports inspect data.
- `fuchsia.inspect.deprecated.Inspect`: A service file. The standard way the Go
  library exports inspect data.

Example usage:

```
$ iquery list-files /hub /dev
/dev/diagnostics/driver_manager/dm.inspect
/hub/c/archivist.cmx/21352/out/diagnostics/fuchsia.inspect.Tree
/hub/c/archivist.cmx/21352/system_diagnostics/fuchsia.inspect.Tree
/hub/c/bt-gap.cmx/35231/out/diagnostics/bt-gap.inspect
/hub/c/bt-gap.cmx/35231/system_diagnostics/fuchsia.inspect.Tree
/hub/c/netstack.cmx/26786/out/diagnostics/counters/fuchsia.inspect.deprecated.Inspect
...
```

#### `--help`

Prints usage information about `list-files`.

### `selectors [<selectors...>]`

Lists all available full selectors (component selector + tree selector).

If a component selector is provided, it’ll only print selectors for that component.

If a full selector (component + tree) is provided, it lists all selectors under the given node.

Example usage:

```
$ iquery selectors archivist.cmx:root/fuchsia.inspect.Health timekeeper.cmx
archivist.cmx:root/fuchsia.inspect.Health:start_timestamp_nanos
archivist.cmx:root/fuchsia.inspect.Health:status
timekeeper.cmx:root/current:system_uptime_monotonic_nanos
timekeeper.cmx:root/current:utc_nanos
timekeeper.cmx:root:start_time_monotonic_nanos
```

#### `--manifest`

The name that you specified for the manifest file. If this is specified, the
output only contains monikers for components whose URL contains the specified
name.

#### `--help`

Prints usage information about `selectors`


### `show [<selectors...>]`

Prints the inspect hierarchies that match the given selectors.

Example usage:

```
$ iquery show archivist.cmx:root/fuchsia.inspect.Health timekeeper.cmx
archivist.cmx:
  root:
    fuchsia.inspect.Health:
      start_timestamp_nanos = 30305104656
      status = OK
timekeeper.cmx:
  root:
    start_time_monotonic_nanos = 30347000053
    current:
      system_uptime_monotonic_nanos = 61617527688648
      utc_nanos = 1591119246552989779
```

#### `--manifest`

The name that you specified for the manifest file. If this is specified, the
output only contains monikers for components whose URL contains the specified
name.

#### `--help

Prints usage information about `show`.

### `show-file [<paths...>]`

Given a path, prints the inspect data contained in files at the given paths. At the moment this
command only works for v1 components as we only have a v1 hub.

Example usage:

```
$ fx shell iquery show-file /dev/diagnostics/driver_manager/dm.inspect /hub/c/archivist.cmx/21352/out/diagnostics/fuchsia.inspect.Tree
/dev/diagnostics/driver_manager/dm.inspect:
  root:
    device_count = 126
    ...
/hub/c/archivist.cmx/21352/out/diagnostics/fuchsia.inspect.Tree:
  root:
    all_archive_accessor_node:
      archive_accessor_connections_closed = 15
  ...
```

#### `--help`

Prints usage information about `show-file`.

[Inspect API]: /docs/development/diagnostics/inspect/README.md