> For the complete documentation index, see [llms.txt](https://docs.specifyapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.specifyapp.com/guides/specify-sdk-cheatsheet.md).

# Specify SDK Cheatsheet

## Creating Specify and SDTF clients

You will first create a Specify client, then authenticate, then create a SDTF client by fetching the repository token tree.

```typescript
import { createSpecifyClient } from "@specifyapp/sdk";

const specifyClient = createSpecifyClient();
await specifyClient.authenticate("<YOUR_PERSONAL_ACCESS_TOKEN_VAR>");

const sdtfClient = 
  await specifyClient.getSDTFClientByRepositoryName("<YOUR_SPECIFY_REPO_NAME>");
  
  console.log('Repository name',sdtfClient.repository.name)
```

## Updating tokens

The following example is only an overview, if you need more details you can have a look [here](/guides/specify-sdk-usage-101/update-the-tokens.md).

```typescript
import { updaters } from '@specifyapp/sdk'

sdtfClient.update(
  updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }}),
);
```

## Convert a token to XXX

The following example is only an overview, if you need more details you can have a look [here](#convert-a-token-to-xxx).

```typescript
import {
  dimensionToCss,
  breakpointToCss,
  colorToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

const strategy = createResolveAliasStrategy();

const outputs = sdtfClient.mapTokenStates(tokenState => 
  tokenState.matchByType(
    {
      dimension: dimensionToCss(strategy) // Output example: '12px'
      breakpoint: breakpointToCss(strategy) // Output example: '12px'
      color: colorToCss(strategy) // Output example: '#ff00ff'
    }, 
    _ => undefined
  )
);
```

## Execute a parser

The following example is only an overview, if you need more details you can have a look [here](/guides/specify-sdk-usage-101/executing-parsers.md).

```typescript
import { parsers } from '@specify/sdk'

const executePipelines = sdtfClient
  .createParsersPipelines(
    parsers.toCssCustomProperties({ filePath: 'myFile.css' }),
  );
const parsersEngineResults = await executePipelines();
```

## Retrieving data

### Get a specific token

```typescript
const tokenState = sdtfClient.getTokenState(['path', 'to', 'token']);
```

### Get all the tokens

```typescript
const tokenStates = sdtfClient.getAllTokenStates();
```

### Map over all the tokens

```ts
const results = sdtfClient.mapTokenStates(tokenState => ...);
```

### Get a specific group

```typescript
const group = sdtfClient.getGroupState(['path', 'to', 'myGroup']);
```

### Get all the groups

```typescript
const groups = sdtfClient.getAllGroupStates();
```

### Map over all the groups

```ts
const results = sdtfClient.mapGroupStates(tokenState => ...);
```

### Get a specific collection

```typescript
const collection = sdtfClient.getCollectionState(['path', 'to', 'myCollection']);
```

### Get all collections

```typescript
const collections = sdtfClient.getAllCollectionStates();
```

### Map over all the collections

```ts
const results = sdtfClient.mapCollectionStates(tokenState => ...);
```

## Filtering data

### Keeping a sub-graph from a path

If you only want a specific portion of the graph, you can cherry-pick using the `pick` function:

```typescript
const colors = sdtfClient.pick(['colors']);
```

### Keeping the children of a path

If you only want the children of a specific portion of the graph you can use the `pick` function this way:

```typescript
const colors = sdtfClient.pick(['colors', '*']);
```

### Query a specific set of data

You can use the `query` method of the `SDTFClient` to create a copy of the current SDTF with only the tokens that'll match your query:

```ts
const colorAndTextStyleOnlySdtf = sdtfClient.query({
  where: {
    token: '.*',
    withTypes: {
      include: ['color', 'textStyle']
    }
  }
});
```

You can find all the details about querying the data [here](/guides/querying-a-sdtf-graph.md).

### Remove tokens from the SDTF

You can use the `remove` method to delete tokens based on a query:

```typescript
sdtfClient
  .remove({ where: { token: '^Blue$', select: true } })
```

## Renaming tokens

### Rename a node

By not specifying any type, the method will rename any node as long as the path is valid.

```typescript
sdtfClient.renameNode({ atPath: ['my', 'path' ], name: 'newName' });
```

### Rename a collection

By specifying the type, the method will rename only a collection node.

```typescript
sdtfClient.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'collection'
});
```

### Rename a group

By specifying the type, the method will rename only a group node.

```typescript
sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'group'
});
```

### Rename a token

By specifying the type, the method will rename only a token node.

```typescript
sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'token'
});
```