---
layout: docs
page_title: search - Command
description: >-
  The "search" command searches the local cache for information about session and target resources.
---

# search

Command: `boundary search`

The `search` command lets you search Boundary's local cache for information about sessions and targets.

For more information, refer to [Boundary `list` vs `search`](/boundary/docs/api-clients/client-cache/#boundary-list-vs-search).

## Examples

The following example searches the local cache for all TCP targets that have the word "Generated" in the name.

```shell-session
$ boundary search -resource targets -query 'type="tcp" and name%"Generated"'
```

**Example output:**

<CodeBlockConfig hideClipboard>

```plaintext
Target information:
  ID:                  ttcp_0987654321
    Scope ID:          p_1234567890
    Version:           2
    Type:              tcp
    Name:              Generated target using host sources
    Description:       Provides a target using host sources in Boundary
    Authorized Actions:
      no-op
      read
      update
      delete
      add-host-sources
      set-host-sources
      remove-host-sources
      add-credential-sources
      set-credential-sources
      remove-credential-sources
      authorize-session

  ID:                  ttcp_1234567890
    Scope ID:          p_1234567890
    Version:           1
    Type:              tcp
    Name:              Generated target with a direct address
    Description:       Provides an initial target using an address in Boundary
    Address:           127.8.0.1
    Authorized Actions:
      no-op
      read
      update
      delete
      add-host-sources
      set-host-sources
      remove-host-sources
      add-credential-sources
      set-credential-sources
      remove-credential-sources
      authorize-session
```

</CodeBlockConfig>



## Usage

<CodeBlockConfig hideClipboard>

```shell-session
$ boundary search [options]
```

</CodeBlockConfig>

### Command options

- `-resource` `(string: "")` - The type of resource you want to search the cache for.
This is a required field.
You can search for the following:
   - `sessions` - Searches for any sessions associated with the user.
   - `targets` - Searches for any targets associated with the user.

- `-query` `(optional)` - If set, specifies the [MQL](https://github.com/hashicorp/mql/blob/main/GRAMMAR.md) query you want to use to search for the indexed fields on the resource you specified.
If you do not provide a `-query` value, the search lists all resources of the specified type that have been cached.
The available fields that can be used in the search query for each resource include:

   - targets: id, name, description, type, address, scope_id
   - sessions: id, type, endpoint, status, scope_id, target_id, user_id

- `token` - A URL that points to a file on disk (file://) from which Boundary reads a token or an environment variable (env://) from which the token will be read.
If you set this parameter, it overrides the `token-name` parameter.
- `token-name` - If specified, Boundary uses the value in this parameter as the name when it stores the token in the system credential store.
You can use this value to switch user identities for different commands.
You can also specify a token name using the **BOUNDARY_TOKEN_NAME** environment variable.


@include 'cmd-option-note.mdx'