> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Issues, projects, teams, cycles, and workflows.

Linear is included in Archal's environment catalog. Use it in a sandbox for issues, projects, teams, cycles, and workflows.

| | |
| - | - |
| Environment ID | `linear` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.linear` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

> [!NOTE]
>
> Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

* GraphQL fields outside the published schema are intentionally rejected.

## Curated starting states

List the five samples with `archal sample list linear`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

> [accordion] Linear privacy-review baseline
>
> Read one team and one issue, then create a second issue against that exact team.
>
> **Sample ID:** `linear.privacy-review.v1`
>
> **Category:** `minimal`
>
> **Starting state:** 12 records across `issues`: 1, `labels`: 2, `organization`: 1, `teams`: 1, `users`: 2, `workflowStates`: 5
>
> **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`
>
> **First read:** `POST /graphql`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "query": "query { viewer { id name email } }"
> }
> ```
>
> **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
>   "variables": {
>     "input": {
>       "teamId": "00000000-0000-4000-8000-100000000010",
>       "title": "Add contract coverage for duplicate webhook delivery"
>     }
>   }
> }
> ```
>
> **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * GraphQL fields outside the published schema are intentionally rejected.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show linear.privacy-review.v1 --raw > archal-linear-privacy-review.json
> archal state validate linear archal-linear-privacy-review.json
> archal session create linear \
>   --state linear=archal-linear-privacy-review.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show linear.privacy-review.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/linear/privacy-review/state.json` and is 4,899 bytes. The CLI verifies SHA-256 `d7338aea77f8e1c789e3d589b3cc0ab3097758c2ed02d74033d7ffb42a875690` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Linear small engineering team
>
> Exercise issues, project, cycle, comments, customers, releases, and team membership for three engineers.
>
> **Sample ID:** `linear.engineering-team.v1`
>
> **Category:** `small-team`
>
> **Starting state:** 79 records across `agentActivities`: 1, `agentSessions`: 1, `attachments`: 1, `auditEntries`: 1, `comments`: 3, `customerNeeds`: 2, `customers`: 2, `customerStatuses`: 2, `customerTiers`: 2, `customViews`: 1, `cycles`: 1, `documents`: 1, `emailIntakeAddresses`: 1, `emojis`: 1, `entityExternalLinks`: 1, `externalUsers`: 1, `favorites`: 1, `gitAutomationStates`: 1, `gitAutomationTargetBranches`: 1, `initiativeUpdates`: 1, `integrations`: 1, `issueRelations`: 1, `issues`: 6, `issueTemplates`: 1, `issueToReleases`: 1, `labels`: 4, `notificationSubscriptions`: 1, `organization`: 1, `organizationInvites`: 4, `projectLabels`: 2, `projectMilestones`: 2, `projects`: 1, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `releasePipelines`: 1, `releases`: 2, `releaseStages`: 2, `teamMemberships`: 3, `teams`: 1, `templates`: 1, `timeSchedules`: 1, `triageResponsibilities`: 1, `users`: 3, `viewPreferences`: 1, `workflowStates`: 6
>
> **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`
>
> **First read:** `POST /graphql`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "query": "query { viewer { id name email } }"
> }
> ```
>
> **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
>   "variables": {
>     "input": {
>       "teamId": "d4e5f6a7-b8c9-4123-8efa-123456789012",
>       "title": "Add contract coverage for duplicate webhook delivery"
>     }
>   }
> }
> ```
>
> **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * GraphQL fields outside the published schema are intentionally rejected.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show linear.engineering-team.v1 --raw > archal-linear-engineering-team.json
> archal state validate linear archal-linear-engineering-team.json
> archal session create linear \
>   --state linear=archal-linear-engineering-team.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show linear.engineering-team.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/linear/engineering-team/state.json` and is 35,798 bytes. The CLI verifies SHA-256 `f0f8ae08dd29f98f2ba2b8c1f7eee52781825ebceacc392e013fdf4f025c0510` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Linear populated backlog
>
> Exercise backlog ordering, filtering, cycles, projects, comments, and triage over twenty-five issues.
>
> **Sample ID:** `linear.busy-backlog.v1`
>
> **Category:** `populated`
>
> **Starting state:** 68 records across `comments`: 6, `customViews`: 1, `cycles`: 2, `issueRelations`: 2, `issues`: 25, `issueTemplates`: 1, `labels`: 5, `organization`: 1, `projectMilestones`: 2, `projects`: 3, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `teamMemberships`: 3, `teams`: 1, `triageResponsibilities`: 1, `users`: 3, `workflowStates`: 6
>
> **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`
>
> **First read:** `POST /graphql`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "query": "query { viewer { id name email } }"
> }
> ```
>
> **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
>   "variables": {
>     "input": {
>       "teamId": "bb020001-b1b1-4001-8001-000000000001",
>       "title": "Add contract coverage for duplicate webhook delivery"
>     }
>   }
> }
> ```
>
> **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * GraphQL fields outside the published schema are intentionally rejected.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show linear.busy-backlog.v1 --raw > archal-linear-busy-backlog.json
> archal state validate linear archal-linear-busy-backlog.json
> archal session create linear \
>   --state linear=archal-linear-busy-backlog.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show linear.busy-backlog.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/linear/busy-backlog/state.json` and is 51,642 bytes. The CLI verifies SHA-256 `ac2b5376d3244952f87fde8fbcdde6a7b363a84bb6c0f8f0e5d28698e1fa1944` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Linear cycle close with unmerged PR
>
> Inspect a completed-looking issue with an explicitly open GitHub pull request, then record the release-blocking cycle-close decision.
>
> **Sample ID:** `linear.cycle-close-unmerged-pr.v1`
>
> **Category:** `edge-case`
>
> **Starting state:** 30 records across `attachments`: 1, `comments`: 3, `cycles`: 1, `issues`: 9, `labels`: 4, `projects`: 1, `teams`: 1, `users`: 4, `workflowStates`: 6
>
> **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`
>
> **First read:** `POST /graphql`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "query": "query CycleCloseIssue($id: String!) { issue(id: $id) { id identifier title completedAt state { id name type } cycle { id name number } attachments { nodes { id title subtitle url } pageInfo { hasNextPage endCursor } } comments { nodes { id body createdAt } pageInfo { hasNextPage endCursor } } } }",
>   "variables": {
>     "id": "BE-445"
>   }
> }
> ```
>
> **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "query": "mutation CycleCloseDecision($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id body } } }",
>   "variables": {
>     "input": {
>       "body": "Cycle-close decision: keep BE-445 marked complete for reporting, but block the release until GitHub pull request #206 is merged.",
>       "issueId": "BE-445"
>     }
>   }
> }
> ```
>
> **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * GraphQL fields outside the published schema are intentionally rejected.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show linear.cycle-close-unmerged-pr.v1 --raw > archal-linear-cycle-close-unmerged-pr.json
> archal state validate linear archal-linear-cycle-close-unmerged-pr.json
> archal session create linear \
>   --state linear=archal-linear-cycle-close-unmerged-pr.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show linear.cycle-close-unmerged-pr.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/linear/cycle-close-unmerged-pr/state.json` and is 20,127 bytes. The CLI verifies SHA-256 `e0a19dac6d1319b139fb65dcd5ad73649d079f9ef0186acd32d6b07134e2b8eb` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] Linear engineering roadmap workflow
>
> Start from a two-team roadmap with projects, cycles, documents, an initiative, and notifications, then create and reset one issue.
>
> **Sample ID:** `linear.engineering-roadmap.v1`
>
> **Category:** `workflow`
>
> **Starting state:** 50 records across `comments`: 2, `customViews`: 2, `cycles`: 2, `documents`: 3, `favorites`: 3, `initiativeProjects`: 1, `initiatives`: 1, `issues`: 5, `issueTemplates`: 2, `labels`: 5, `notifications`: 4, `projects`: 2, `roadmaps`: 1, `teams`: 2, `users`: 5, `workflowStates`: 10
>
> **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`
>
> **First read:** `POST /graphql`. Expected result: HTTP 200.
>
> **First-read input**
>
> ```json theme={null}
> {
>   "query": "query { viewer { id name email } }"
> }
> ```
>
> **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
>   "variables": {
>     "input": {
>       "teamId": "b0000001-0001-4001-8001-000000000001",
>       "title": "Add contract coverage for duplicate webhook delivery"
>     }
>   }
> }
> ```
>
> **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * GraphQL fields outside the published schema are intentionally rejected.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show linear.engineering-roadmap.v1 --raw > archal-linear-engineering-roadmap.json
> archal state validate linear archal-linear-engineering-roadmap.json
> archal session create linear \
>   --state linear=archal-linear-engineering-roadmap.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show linear.engineering-roadmap.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/linear/engineering-roadmap/state.json` and is 25,645 bytes. The CLI verifies SHA-256 `9e8ccb4537eee555402f8ef2c83b1a0f3817ab3b8fbcdae02be806fb0796c307` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe linear`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate linear state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state.md) before replacing state in an existing sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.