From c276c1508c0c6c46ac37eb0226c46002b8187986 Mon Sep 17 00:00:00 2001
From: Peter Schilling <code@schpet.com>
Date: Fri, 4 Sep 2026 11:30:14 -0700
Subject: [PATCH] Accept team names and IDs, and state names, wherever the CLI
 takes them

Every command that takes a team now accepts its key, name, or UUID through
one shared resolver (findTeam / resolveTeam / resolveTeams), replacing the
key-only getTeamIdByKey and the ad-hoc uppercasing spread across commands.
One aliased ResolveTeam operation looks up key, name, and (for UUID-shaped
input) id in a single round trip; precedence is key, then id, then name,
applied client-side so a reference that equals one team's key and another
team's name always means the key. Keys stay the canonical downstream form:
filters that matched on team.key still do, with the server's uppercase key,
and callers that need a UUID take it from the same resolved object. An
unknown team now errors with the list of valid keys instead of an empty
result or a raw "Entity not found" from the API.

Only explicit input goes through the resolver. The configured default team
is already a normalized key, and resolving it would add a round trip to
every default-team invocation of the most-used commands for no gain. In
issue create, the interactive substring picker survives only for that
default; an explicit --team that matches nothing errors like everywhere
else.

issue query --state and issue mine --state take a workflow state name or
ID as well as the six type tokens. Names and IDs are resolved within the
queried scope (the team, the teams, or the whole workspace under
--all-teams, where a name matches every team's same-named state), so a
state from another team errors instead of silently matching nothing, and
the error lists the scope's states. Type-only input still sends the same
{ type: { in } } filter with no extra request; a mix of types and names
becomes an or-filter.

The MCP server already describes these parameters as "key, name, or ID"
and "type, name, or ID"; this brings the CLI to parity so an agent does
not need a preliminary team list to translate a name into a key.

Claude-Session: https://claude.ai/code/session_01A9qEGri4p2HZMQSuYsBmub
---
 CHANGELOG.md                                  |   2 +
 README.md                                     |   3 +-
 docs/usage.md                                 |  12 +-
 skills/linear-cli/references/cycle.md         |  12 +-
 skills/linear-cli/references/document.md      |   7 +-
 skills/linear-cli/references/issue.md         |  88 ++--
 skills/linear-cli/references/label.md         |  31 +-
 skills/linear-cli/references/project.md       |   6 +-
 skills/linear-cli/references/team.md          |  34 +-
 src/commands/cycle/cycle-list.ts              |  12 +-
 src/commands/cycle/cycle-view.ts              |  12 +-
 src/commands/document/attachment-target.ts    |  14 +-
 src/commands/document/document-create.ts      |   2 +-
 src/commands/document/document-list.ts        |   2 +-
 src/commands/document/document-update.ts      |   2 +-
 src/commands/issue/issue-create.ts            |  64 +--
 src/commands/issue/issue-mine.ts              |  41 +-
 src/commands/issue/issue-query.ts             |  71 ++--
 src/commands/issue/issue-start.ts             |   2 +-
 src/commands/issue/issue-update.ts            |  21 +-
 src/commands/label/label-create.ts            |  18 +-
 src/commands/label/label-delete.ts            |  13 +-
 src/commands/label/label-list.ts              |  17 +-
 src/commands/project/project-create.ts        |  13 +-
 src/commands/project/project-list.ts          |  58 +--
 src/commands/project/project-update.ts        |  15 +-
 src/commands/team/team-delete.ts              |  18 +-
 src/commands/team/team-members.ts             |  17 +-
 src/commands/team/team-states.ts              |  21 +-
 src/utils/linear.ts                           | 338 ++++++++++++++-
 .../__snapshots__/cycle-list.test.ts.snap     |  32 +-
 .../__snapshots__/cycle-view.test.ts.snap     |   6 +-
 test/commands/cycle/cycle-list.test.ts        |  60 ++-
 test/commands/cycle/cycle-view.test.ts        |  22 +-
 .../document-create.test.ts.snap              |   2 +-
 .../__snapshots__/document-list.test.ts.snap  |  16 +-
 .../document-update.test.ts.snap              |   3 +-
 .../commands/document/document-create.test.ts |  26 +-
 test/commands/document/document-list.test.ts  |  69 ++-
 .../commands/document/document-update.test.ts |  12 +-
 .../__snapshots__/issue-create.test.ts.snap   |  21 +-
 .../__snapshots__/issue-list.test.ts.snap     |  36 +-
 .../__snapshots__/issue-mine.test.ts.snap     |  54 ++-
 .../__snapshots__/issue-query.test.ts.snap    | 313 ++++++++++++--
 .../__snapshots__/issue-update.test.ts.snap   |  13 +-
 test/commands/issue/issue-create.test.ts      | 194 ++++++---
 test/commands/issue/issue-list.test.ts        |   6 +-
 test/commands/issue/issue-mine.test.ts        | 161 ++++++-
 test/commands/issue/issue-query.test.ts       | 237 ++++++++++-
 test/commands/issue/issue-update.test.ts      | 362 ++++++++++++----
 .../__snapshots__/label-create.test.ts.snap   |  34 ++
 .../__snapshots__/label-delete.test.ts.snap   |  29 ++
 .../__snapshots__/label-list.test.ts.snap     |  25 ++
 test/commands/label/label-create.test.ts      |  61 +++
 test/commands/label/label-delete.test.ts      |  71 ++++
 test/commands/label/label-list.test.ts        |  54 ++-
 .../__snapshots__/project-create.test.ts.snap |  12 +-
 .../__snapshots__/project-list.test.ts.snap   |  23 +-
 .../__snapshots__/project-update.test.ts.snap |   2 +-
 test/commands/project/project-create.test.ts  | 101 ++++-
 test/commands/project/project-list.test.ts    |  47 ++
 .../__snapshots__/team-delete.test.ts.snap    |  38 ++
 .../__snapshots__/team-members.test.ts.snap   |   4 +-
 .../__snapshots__/team-states.test.ts.snap    |  74 +++-
 test/commands/team/team-delete.test.ts        | 113 +++++
 test/commands/team/team-members.test.ts       |   7 +
 test/commands/team/team-states.test.ts        |  77 ++++
 test/utils/linear.test.ts                     | 400 ++++++++++++++++++
 test/utils/test-helpers.ts                    |  18 +
 69 files changed, 3197 insertions(+), 604 deletions(-)
 create mode 100644 test/commands/label/__snapshots__/label-create.test.ts.snap
 create mode 100644 test/commands/label/__snapshots__/label-delete.test.ts.snap
 create mode 100644 test/commands/label/label-create.test.ts
 create mode 100644 test/commands/label/label-delete.test.ts
 create mode 100644 test/commands/team/__snapshots__/team-delete.test.ts.snap
 create mode 100644 test/commands/team/team-delete.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 820c2b6a..db0ed4b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Added
 
+- every command that takes a team now accepts its key, name, or UUID, resolved through one shared lookup: `team states`, `team members`, `team delete`, `label list/create/delete --team`, `cycle list/view --team`, `project list/create/update --team`, `document list/create/update --team`, and `issue query/mine/create/update --team`. Keys stay canonical and win over a same-spelled name; an unknown team errors with the list of valid keys instead of an empty result or a raw API error. Previously only keys worked, which is why [#276](https://github.com/schpet/linear-cli/issues/276) asked for `team list --json` as a name-to-key lookup
+- `issue query --state` and `issue mine --state` accept a workflow state name or ID as well as the six state types, looked up within the queried team scope (all teams under `--all-teams`, where a name matches every team's same-named state). An unknown name errors and lists the scope's states, and types and names can be mixed
 - `project update --content <markdown>` and `--content-file <path>` replace a project's long-form overview body, matching the flags `project create` already had. Previously the only way to change the body after creation was a hand-written `projectUpdate` mutation through `linear api`
 - `--json` (`-j`) on `team list`, `cycle list`, `cycle view`, `milestone list`, `milestone view`, and `project view`, the last read commands without machine-readable output. List commands emit the same `{ nodes, pageInfo }` connection shape as the other list commands, after the same filtering and ordering as the table; view commands emit the GraphQL object as fetched, including every issue rather than the ten-item preview, and `milestone view --all --json` includes every page. (A 2.0.0 entry claimed `cycle list --json`; that change never actually landed.) ([#276](https://github.com/schpet/linear-cli/issues/276); thanks @lakardion)
 
diff --git a/README.md b/README.md
index 1bb974cf..3d6caa4b 100644
--- a/README.md
+++ b/README.md
@@ -137,6 +137,7 @@ linear issue list -w   # open issue list in web browser
 linear issue list -a   # open issue list in Linear.app
 linear issue query --search "login bug"  # search issues by text in your configured team
 linear issue query --search "oauth timeout" --team ENG --json  # structured search output for agents
+linear issue query --team "Engineering" --state "In Review" --json  # teams by key, name, or ID; states by type, name, or ID
 linear issue query --all-teams --json --limit 0  # export all issues as JSON
 linear issue start     # create/switch to issue branch and mark as started
 linear issue create    # create a new issue (interactive prompts)
@@ -205,7 +206,7 @@ linear project update <projectId> --content-file overview.md  # replace the proj
 ### cycle commands
 
 ```bash
-linear cycle list --team ENG          # list a team's cycles
+linear cycle list --team ENG          # list a team's cycles (--team takes a key, name, or ID)
 linear cycle list --team ENG --json   # as JSON
 linear cycle view 12 --team ENG       # view a cycle by number or name
 linear cycle view 12 --team ENG --json  # cycle details and its issues, as JSON
diff --git a/docs/usage.md b/docs/usage.md
index cb481cb2..df690608 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -35,6 +35,10 @@ linear issue list --all-states
 
 # List multiple states
 linear issue list --state unstarted --state started
+
+# A state name or ID works too, and mixes with types
+linear issue list --state "In Review"
+linear issue list --state started --state "In Review"
 ```
 
 filter by assignee:
@@ -56,8 +60,9 @@ linear issue list --all-assignees
 other options:
 
 ```bash
-# List issues for specific team
+# List issues for specific team (key, name, or ID)
 linear issue list --team TEAM
+linear issue list --team "Team Name"
 
 # Sort by priority instead of manual order
 linear issue list --sort priority
@@ -138,7 +143,7 @@ linear issue create --estimate 3
 # Create with labels
 linear issue create --label bug --label frontend
 
-# Create for specific team
+# Create for specific team (key, name, or ID)
 linear issue create --team TEAM
 
 # Create and start working on it
@@ -210,6 +215,8 @@ linear issue delete TEAM-123
 
 ### teams
 
+wherever a command takes a team, pass its key, its name, or its UUID. keys are canonical; an unknown team errors and lists the valid keys.
+
 #### list teams
 
 ```bash
@@ -237,6 +244,7 @@ list members of a specific team:
 
 ```bash
 linear team members TEAM
+linear team members "Team Name"
 ```
 
 #### create a team
diff --git a/skills/linear-cli/references/cycle.md b/skills/linear-cli/references/cycle.md
index 762b4f37..a2500685 100644
--- a/skills/linear-cli/references/cycle.md
+++ b/skills/linear-cli/references/cycle.md
@@ -37,9 +37,9 @@ Description:
 
 Options:
 
-  -h, --help           - Show this help.                      
-  --workspace  <slug>  - Target workspace (uses credentials)  
-  --team       <team>  - Team key (defaults to current team)  
+  -h, --help           - Show this help.                                   
+  --workspace  <slug>  - Target workspace (uses credentials)               
+  --team       <team>  - Team key, name, or ID (defaults to current team)  
   -j, --json           - Output as JSON
 ```
 
@@ -56,8 +56,8 @@ Description:
 
 Options:
 
-  -h, --help           - Show this help.                      
-  --workspace  <slug>  - Target workspace (uses credentials)  
-  --team       <team>  - Team key (defaults to current team)  
+  -h, --help           - Show this help.                                   
+  --workspace  <slug>  - Target workspace (uses credentials)               
+  --team       <team>  - Team key, name, or ID (defaults to current team)  
   -j, --json           - Output as JSON
 ```
diff --git a/skills/linear-cli/references/document.md b/skills/linear-cli/references/document.md
index 3b81e037..9fecfb2d 100644
--- a/skills/linear-cli/references/document.md
+++ b/skills/linear-cli/references/document.md
@@ -53,7 +53,7 @@ Options:
   --project           <project>     - Attach to project (UUID, slug ID, or name)                                        
   --issue             <issue>       - Attach to issue (identifier like TC-123)                                          
   --initiative        <initiative>  - Attach to initiative (UUID, slug ID, or name)                                     
-  --team              <team>        - Attach to team (key); with --cycle, scopes the cycle lookup instead               
+  --team              <team>        - Attach to team (key, name, or ID); with --cycle, scopes the cycle lookup instead  
   --cycle             <cycle>       - Attach to cycle: name, number, 'active'/'now', 'next', 'previous', or a relative  
                                       offset like +1 (team from --team or config)                                       
   --release           <release>     - Attach to release (UUID, name, or version)                                        
@@ -100,7 +100,7 @@ Options:
   --project     <project>     - Filter by project (UUID, slug ID, or name)                                                     
   --issue       <issue>       - Filter by issue (identifier like TC-123)                                                       
   --initiative  <initiative>  - Filter by initiative (UUID, slug ID, or name)                                                  
-  --team        <team>        - Filter by team (key); with --cycle, scopes the cycle lookup instead                            
+  --team        <team>        - Filter by team (key, name, or ID); with --cycle, scopes the cycle lookup instead               
   --cycle       <cycle>       - Filter by cycle: name, number, 'active'/'now', 'next', 'previous', or a relative               
                                 offset like +1 (team from --team or config)                                                    
   --release     <release>     - Filter by release (UUID, name, or version)                                                     
@@ -135,7 +135,8 @@ Options:
   --project           <project>     - Re-point to project (UUID, slug ID, or name); replaces the current attachment     
   --issue             <issue>       - Re-point to issue (identifier like TC-123); replaces the current attachment       
   --initiative        <initiative>  - Re-point to initiative (UUID, slug ID, or name); replaces the current attachment  
-  --team              <team>        - Re-point to team (key); with --cycle, scopes the cycle lookup instead             
+  --team              <team>        - Re-point to team (key, name, or ID); with --cycle, scopes the cycle lookup        
+                                      instead                                                                           
   --cycle             <cycle>       - Re-point to cycle: name, number, 'active'/'now', 'next', 'previous', or a         
                                       relative offset like +1 (team from --team or config)                              
   --release           <release>     - Re-point to release (UUID, name, or version); replaces the current attachment     
diff --git a/skills/linear-cli/references/issue.md b/skills/linear-cli/references/issue.md
index 23fca896..3df9f9d7 100644
--- a/skills/linear-cli/references/issue.md
+++ b/skills/linear-cli/references/issue.md
@@ -271,7 +271,7 @@ Options:
   -d, --description          <description>  - Description of the issue                                                      
   --description-file         <path>         - Read description from a file (preferred for markdown content)                 
   -l, --label                <label>        - Issue label associated with the issue. May be repeated.                       
-  --team                     <team>         - Team associated with the issue (if not your default team)                     
+  --team                     <team>         - Team (key, name, or ID) for the issue, if not your default team               
   --project                  <project>      - Project for the issue (UUID, slug ID, or name)                                
   -s, --state                <state>        - Workflow state for the issue (by name or type)                                
   --milestone                <milestone>    - Project milestone (UUID, or name when --project is set)                       
@@ -375,24 +375,24 @@ Description:
 
 Options:
 
-  -h, --help                       - Show this help.                                                                                                                         
-  --workspace      <slug>          - Target workspace (uses credentials)                                                                                                     
-  -s, --state      <state>         - Filter by issue state (can be repeated for multiple states)                      (Default: [ "unstarted" ], Values: "triage", "backlog",
-                                                                                                                      "unstarted", "started", "completed", "canceled")       
-  --all-states                     - Show issues from all states                                                                                                             
-  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: "manual", "priority")                         
-  --team           <team>          - Team to list issues for (if not your default team)                                                                                      
-  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                                              
-  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                                           
-  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                                         
-                                     offset like +1                                                                                                                          
-  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                                                       
-  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                                              
-  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: 50)                                          
-  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  -w, --web                        - Open in web browser                                                                                                                     
-  -a, --app                        - Open in Linear.app                                                                                                                      
+  -h, --help                       - Show this help.                                                                                                
+  --workspace      <slug>          - Target workspace (uses credentials)                                                                            
+  -s, --state      <state>         - Filter by workflow state type (triage, backlog, unstarted, started, completed,   (Default: [ "unstarted" ])    
+                                     canceled), name, or ID (can be repeated for multiple states)                                                   
+  --all-states                     - Show issues from all states                                                                                    
+  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: "manual", "priority")
+  --team           <team>          - Team key, name, or ID to list issues for (if not your default team)                                            
+  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                     
+  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                  
+  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                
+                                     offset like +1                                                                                                 
+  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                              
+  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                     
+  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: 50)                 
+  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  -w, --web                        - Open in web browser                                                                                            
+  -a, --app                        - Open in Linear.app                                                                                             
   --no-pager                       - Disable automatic paging for long output
 ```
 
@@ -434,30 +434,30 @@ Description:
 
 Options:
 
-  -h, --help                           - Show this help.                                                                                                                       
-  --workspace          <slug>          - Target workspace (uses credentials)                                                                                                   
-  --search             <term>          - Full-text search term                                                                                                                 
-  --search-comments                    - Also search inside issue comments (requires --search)                                                                                 
-  --team               <team>          - Filter by team key (can be repeated for multiple teams)                                                                               
-  --all-teams                          - Query across all teams                                                                                                                
-  -s, --state          <state>         - Filter by issue state (can be repeated for multiple states)                      (Values: "triage", "backlog", "unstarted", "started",
-                                                                                                                          "completed", "canceled")                             
-  --all-states                         - Show issues from all states (this is the default)                                                                                     
-  --assignee           <assignee>      - Filter by assignee (username)                                                                                                         
-  -A, --all-assignees                  - Show issues for all assignees (this is the default)                                                                                   
-  -U, --unassigned                     - Show only unassigned issues                                                                                                           
-  --sort               <sort>          - Sort order: manual or priority (default: priority, not available with --search)  (Values: "manual", "priority")                       
-  --project            <project>       - Filter by project (UUID, slug ID, or name)                                                                                            
-  --project-label      <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                                         
-  --cycle              <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                                       
-                                         offset like +1                                                                                                                        
-  --milestone          <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                                                     
-  -l, --label          <label>         - Filter by label name (can be repeated for multiple labels)                                                                            
-  --limit              <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: 50)                                        
-  --created-after      <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                                        
-  --updated-after      <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                                        
-  --include-archived                   - Include archived issues                                                                                                               
-  -j, --json                           - Output results as JSON                                                                                                                
+  -h, --help                           - Show this help.                                                                                                
+  --workspace          <slug>          - Target workspace (uses credentials)                                                                            
+  --search             <term>          - Full-text search term                                                                                          
+  --search-comments                    - Also search inside issue comments (requires --search)                                                          
+  --team               <team>          - Filter by team key, name, or ID (can be repeated for multiple teams)                                           
+  --all-teams                          - Query across all teams                                                                                         
+  -s, --state          <state>         - Filter by workflow state type (triage, backlog, unstarted, started, completed,                                 
+                                         canceled), name, or ID (can be repeated for multiple states)                                                   
+  --all-states                         - Show issues from all states (this is the default)                                                              
+  --assignee           <assignee>      - Filter by assignee (username)                                                                                  
+  -A, --all-assignees                  - Show issues for all assignees (this is the default)                                                            
+  -U, --unassigned                     - Show only unassigned issues                                                                                    
+  --sort               <sort>          - Sort order: manual or priority (default: priority, not available with --search)  (Values: "manual", "priority")
+  --project            <project>       - Filter by project (UUID, slug ID, or name)                                                                     
+  --project-label      <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                  
+  --cycle              <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                
+                                         offset like +1                                                                                                 
+  --milestone          <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                              
+  -l, --label          <label>         - Filter by label name (can be repeated for multiple labels)                                                     
+  --limit              <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: 50)                 
+  --created-after      <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --updated-after      <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --include-archived                   - Include archived issues                                                                                        
+  -j, --json                           - Output results as JSON                                                                                         
   --no-pager                           - Disable automatic paging for long output
 ```
 
@@ -609,7 +609,7 @@ Options:
   --add-label         <label>        - Add a label to the issue, keeping its existing labels. May be repeated.          
   --remove-label      <label>        - Remove a label from the issue, keeping its other labels (does not delete the     
                                        label from the team). May be repeated.                                           
-  --team              <team>         - Team associated with the issue (if not your default team)                        
+  --team              <team>         - Team (key, name, or ID) to move the issue to                                     
   --project           <project>      - Project to assign the issue to (UUID, slug ID, or name)                          
   -s, --state         <state>        - Workflow state for the issue (by name or type)                                   
   --milestone         <milestone>    - Project milestone (UUID, or name when --project is set or the issue already has  
diff --git a/skills/linear-cli/references/label.md b/skills/linear-cli/references/label.md
index 4bd22ca8..bd8faa5c 100644
--- a/skills/linear-cli/references/label.md
+++ b/skills/linear-cli/references/label.md
@@ -38,12 +38,12 @@ Description:
 
 Options:
 
-  -h, --help                        - Show this help.                                              
-  --workspace        <slug>         - Target workspace (uses credentials)                          
-  -n, --name         <name>         - Label name (required)                                        
-  -c, --color        <color>        - Color hex code (e.g., #EB5757)                               
-  -d, --description  <description>  - Label description                                            
-  -t, --team         <teamKey>      - Team key for team-specific label (omit for workspace label)  
+  -h, --help                        - Show this help.                                                             
+  --workspace        <slug>         - Target workspace (uses credentials)                                         
+  -n, --name         <name>         - Label name (required)                                                       
+  -c, --color        <color>        - Color hex code (e.g., #EB5757)                                              
+  -d, --description  <description>  - Label description                                                           
+  -t, --team         <team>         - Team key, name, or ID for a team-specific label (omit for workspace label)  
   -i, --interactive                 - Interactive mode (default if no flags provided)
 ```
 
@@ -60,10 +60,10 @@ Description:
 
 Options:
 
-  -h, --help              - Show this help.                                 
-  --workspace  <slug>     - Target workspace (uses credentials)             
-  -t, --team   <teamKey>  - Team key to disambiguate labels with same name  
-  -f, --force             - Skip confirmation prompt
+  -h, --help           - Show this help.                                                  
+  --workspace  <slug>  - Target workspace (uses credentials)                              
+  -t, --team   <team>  - Team key, name, or ID to disambiguate labels with the same name  
+  -f, --force          - Skip confirmation prompt
 ```
 
 ### list
@@ -79,9 +79,10 @@ Description:
 
 Options:
 
-  -h, --help              - Show this help.                                              
-  --team       <teamKey>  - Filter by team (e.g., TC). Shows team-specific labels only.  
-  --workspace             - Show only workspace-level labels (not team-specific)         
-  --all                   - Show all labels (both workspace and team)                    
-  -j, --json              - Output as JSON
+  -h, --help           - Show this help.                                                            
+  --team       <team>  - Filter by team key, name, or ID (e.g., TC). Shows that team's labels plus  
+                         workspace labels.                                                          
+  --workspace          - Show only workspace-level labels (not team-specific)                       
+  --all                - Show all labels (both workspace and team)                                  
+  -j, --json           - Output as JSON
 ```
diff --git a/skills/linear-cli/references/project.md b/skills/linear-cli/references/project.md
index ab4e5257..2f05f728 100644
--- a/skills/linear-cli/references/project.md
+++ b/skills/linear-cli/references/project.md
@@ -53,7 +53,7 @@ Options:
                                            limit)                                                                      
   --content               <markdown>     - Project overview markdown                                                   
   --content-file          <path>         - Read project overview markdown from a file                                  
-  -t, --team              <team>         - Team key (required, can be repeated for multiple teams)                     
+  -t, --team              <team>         - Team key, name, or ID (required, can be repeated for multiple teams)        
   -l, --lead              <lead>         - Project lead (username, email, or @me)                                      
   -s, --status            <status>       - Project status (planned, started, paused, completed, canceled, backlog)     
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                     
@@ -101,7 +101,7 @@ Options:
 
   -h, --help             - Show this help.                      
   --workspace  <slug>    - Target workspace (uses credentials)  
-  --team       <team>    - Filter by team key                   
+  --team       <team>    - Filter by team key, name, or ID      
   --all-teams            - Show projects from all teams         
   --status     <status>  - Filter by status name                
   -w, --web              - Open in web browser                  
@@ -139,7 +139,7 @@ Options:
   -l, --lead              <lead>         - Project lead (username, email, or @me)                                      
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                     
   --target-date           <targetDate>   - Target date (YYYY-MM-DD)                                                    
-  -t, --team              <team>         - Team key (can be repeated for multiple teams)                               
+  -t, --team              <team>         - Team key, name, or ID (can be repeated for multiple teams)                  
   --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.
 ```
 
diff --git a/skills/linear-cli/references/team.md b/skills/linear-cli/references/team.md
index ebc73cfd..978e00cc 100644
--- a/skills/linear-cli/references/team.md
+++ b/skills/linear-cli/references/team.md
@@ -18,13 +18,13 @@ Options:
 
 Commands:
 
-  create                - Create a linear team                                                         
-  delete     <teamKey>  - Delete a Linear team                                                         
-  list                  - List teams                                                                   
-  id                    - Print the configured team id                                                 
-  autolinks             - Configure GitHub repository autolinks for Linear issues with this team prefix
-  members    [teamKey]  - List team members                                                            
-  states     [teamKey]  - List workflow states for a team
+  create             - Create a linear team                                                         
+  delete     <team>  - Delete a Linear team                                                         
+  list               - List teams                                                                   
+  id                 - Print the configured team id                                                 
+  autolinks          - Configure GitHub repository autolinks for Linear issues with this team prefix
+  members    [team]  - List team members (team by key, name, or ID)                                 
+  states     [team]  - List workflow states for a team (by key, name, or ID)
 ```
 
 ## Subcommands
@@ -73,7 +73,7 @@ Options:
 > Delete a Linear team
 
 ```
-Usage:   linear team delete <teamKey>
+Usage:   linear team delete <team>
 
 Description:
 
@@ -81,9 +81,9 @@ Description:
 
 Options:
 
-  -h, --help                   - Show this help.                                  
-  --workspace    <slug>        - Target workspace (uses credentials)              
-  --move-issues  <targetTeam>  - Move all issues to another team before deletion  
+  -h, --help                   - Show this help.                                                     
+  --workspace    <slug>        - Target workspace (uses credentials)                                 
+  --move-issues  <targetTeam>  - Move all issues to another team (key, name, or ID) before deletion  
   -y, --force                  - Skip confirmation prompt
 ```
 
@@ -126,14 +126,14 @@ Options:
 
 ### members
 
-> List team members
+> List team members (team by key, name, or ID)
 
 ```
-Usage:   linear team members [teamKey]
+Usage:   linear team members [team]
 
 Description:
 
-  List team members
+  List team members (team by key, name, or ID)
 
 Options:
 
@@ -145,14 +145,14 @@ Options:
 
 ### states
 
-> List workflow states for a team
+> List workflow states for a team (by key, name, or ID)
 
 ```
-Usage:   linear team states [teamKey]
+Usage:   linear team states [team]
 
 Description:
 
-  List workflow states for a team
+  List workflow states for a team (by key, name, or ID)
 
 Options:
 
diff --git a/src/commands/cycle/cycle-list.ts b/src/commands/cycle/cycle-list.ts
index 6866bd6e..7b9a478f 100644
--- a/src/commands/cycle/cycle-list.ts
+++ b/src/commands/cycle/cycle-list.ts
@@ -5,7 +5,7 @@ import { gql } from "../../__codegen__/gql.ts"
 import type { GetTeamCyclesQuery } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { padDisplay } from "../../utils/display.ts"
-import { getTeamIdByKey, getTeamKey } from "../../utils/linear.ts"
+import { getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { header, muted } from "../../utils/styling.ts"
 import {
@@ -61,7 +61,10 @@ function formatDate(dateString: string): string {
 export const listCommand = new Command()
   .name("list")
   .description("List cycles for a team")
-  .option("--team <team:string>", "Team key (defaults to current team)")
+  .option(
+    "--team <team:string>",
+    "Team key, name, or ID (defaults to current team)",
+  )
   .option("-j, --json", "Output as JSON")
   .action(async ({ team, json }) => {
     try {
@@ -72,10 +75,7 @@ export const listCommand = new Command()
         )
       }
 
-      const teamId = await getTeamIdByKey(teamKey)
-      if (!teamId) {
-        throw new NotFoundError("Team", teamKey)
-      }
+      const teamId = (await resolveTeam(teamKey)).id
 
       const { Spinner } = await import("@std/cli/unstable-spinner")
       const showSpinner = !json && shouldShowSpinner()
diff --git a/src/commands/cycle/cycle-view.ts b/src/commands/cycle/cycle-view.ts
index d309c37e..0f2d9024 100644
--- a/src/commands/cycle/cycle-view.ts
+++ b/src/commands/cycle/cycle-view.ts
@@ -5,8 +5,8 @@ import { getGraphQLClient } from "../../utils/graphql.ts"
 import { formatRelativeTime } from "../../utils/display.ts"
 import {
   getCycleIdByNameOrNumber,
-  getTeamIdByKey,
   getTeamKey,
+  resolveTeam,
 } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import {
@@ -59,7 +59,10 @@ export const viewCommand = new Command()
   .description("View cycle details")
   .alias("v")
   .arguments("<cycleRef:string>")
-  .option("--team <team:string>", "Team key (defaults to current team)")
+  .option(
+    "--team <team:string>",
+    "Team key, name, or ID (defaults to current team)",
+  )
   .option("-j, --json", "Output as JSON")
   .action(async ({ team, json }, cycleRef) => {
     try {
@@ -70,10 +73,7 @@ export const viewCommand = new Command()
         )
       }
 
-      const teamId = await getTeamIdByKey(teamKey)
-      if (!teamId) {
-        throw new NotFoundError("Team", teamKey)
-      }
+      const teamId = (await resolveTeam(teamKey)).id
 
       const cycleId = await getCycleIdByNameOrNumber(cycleRef, teamId)
 
diff --git a/src/commands/document/attachment-target.ts b/src/commands/document/attachment-target.ts
index 08dc54b9..d930c0c4 100644
--- a/src/commands/document/attachment-target.ts
+++ b/src/commands/document/attachment-target.ts
@@ -3,12 +3,12 @@ import type { DocumentFilter } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import {
   getCycleIdByNameOrNumber,
-  getTeamIdByKey,
   getTeamKey,
   isLinearUuid,
   resolveInitiativeId,
   resolveProjectId,
   resolveReleaseId,
+  resolveTeam,
 } from "../../utils/linear.ts"
 import {
   isClientError,
@@ -139,14 +139,8 @@ async function resolveIssueId(input: string): Promise<string> {
   })
 }
 
-async function resolveTeamIdStrict(teamKey: string): Promise<string> {
-  const teamId = await getTeamIdByKey(teamKey.toUpperCase())
-  if (!teamId) {
-    throw new NotFoundError("Team", teamKey, {
-      suggestion: "Pass a team key, e.g. --team ENG.",
-    })
-  }
-  return teamId
+async function resolveTeamIdStrict(team: string): Promise<string> {
+  return (await resolveTeam(team)).id
 }
 
 async function resolveCycleScopeTeamId(explicitTeam?: string): Promise<string> {
@@ -160,7 +154,7 @@ async function resolveCycleScopeTeamId(explicitTeam?: string): Promise<string> {
     return await resolveTeamIdStrict(configTeam)
   }
   throw new ValidationError("--cycle requires a team to look the cycle up in", {
-    suggestion: "Pass --team <key> or configure a default team.",
+    suggestion: "Pass --team <key, name, or ID> or configure a default team.",
   })
 }
 
diff --git a/src/commands/document/document-create.ts b/src/commands/document/document-create.ts
index 5d699134..35f045b8 100644
--- a/src/commands/document/document-create.ts
+++ b/src/commands/document/document-create.ts
@@ -64,7 +64,7 @@ export const createCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Attach to team (key); with --cycle, scopes the cycle lookup instead",
+    "Attach to team (key, name, or ID); with --cycle, scopes the cycle lookup instead",
   )
   .option(
     "--cycle <cycle:string>",
diff --git a/src/commands/document/document-list.ts b/src/commands/document/document-list.ts
index 92f97c24..7acf9e68 100644
--- a/src/commands/document/document-list.ts
+++ b/src/commands/document/document-list.ts
@@ -110,7 +110,7 @@ export const listCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Filter by team (key); with --cycle, scopes the cycle lookup instead",
+    "Filter by team (key, name, or ID); with --cycle, scopes the cycle lookup instead",
   )
   .option(
     "--cycle <cycle:string>",
diff --git a/src/commands/document/document-update.ts b/src/commands/document/document-update.ts
index e979f106..4d8a8d86 100644
--- a/src/commands/document/document-update.ts
+++ b/src/commands/document/document-update.ts
@@ -202,7 +202,7 @@ export const updateCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Re-point to team (key); with --cycle, scopes the cycle lookup instead",
+    "Re-point to team (key, name, or ID); with --cycle, scopes the cycle lookup instead",
   )
   .option(
     "--cycle <cycle:string>",
diff --git a/src/commands/issue/issue-create.ts b/src/commands/issue/issue-create.ts
index f2778891..72215e97 100644
--- a/src/commands/issue/issue-create.ts
+++ b/src/commands/issue/issue-create.ts
@@ -7,6 +7,7 @@ import { getEditor, openEditor } from "../../utils/editor.ts"
 import { getPriorityDisplay } from "../../utils/display.ts"
 import {
   fetchParentIssueData,
+  findTeam,
   getAllTeams,
   getCycleIdByNameOrNumber,
   getIssueId,
@@ -17,13 +18,13 @@ import {
   getProjectIdByName,
   getProjectOptionsByName,
   getProjectsForTeam,
-  getTeamIdByKey,
   getTeamKey,
   getWorkflowStates,
   isLinearUuid,
   lookupUserId,
   lowestPositionStateOfType,
   resolveMilestoneId,
+  resolveTeam,
   resolveWorkflowState,
   searchTeamsByKeySubstring,
   selectOption,
@@ -403,11 +404,11 @@ async function promptInteractiveIssueCreation(
   const teamResolutionPromise = (async () => {
     const defaultTeamKey = getTeamKey()
     if (defaultTeamKey) {
-      const teamId = await getTeamIdByKey(defaultTeamKey)
-      if (teamId) {
+      const team = await findTeam(defaultTeamKey)
+      if (team) {
         return {
-          teamId: teamId,
-          teamKey: defaultTeamKey,
+          teamId: team.id,
+          teamKey: team.key,
           needsTeamSelection: false,
         }
       }
@@ -637,7 +638,7 @@ export const createCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Team associated with the issue (if not your default team)",
+    "Team (key, name, or ID) for the issue, if not your default team",
   )
   .option(
     "--project <project:string>",
@@ -775,11 +776,8 @@ export const createCommand = new Command()
           console.log(issue.url)
 
           if (interactiveData.start) {
-            const teamKey = issue.team.key
-            const teamIdForStartWork = await getTeamIdByKey(teamKey)
-            if (teamIdForStartWork) {
-              await startWorkOnIssue(issueId, teamIdForStartWork)
-            }
+            const teamIdForStartWork = (await resolveTeam(issue.team.key)).id
+            await startWorkOnIssue(issueId, teamIdForStartWork)
           }
           return
         } catch (error) {
@@ -803,21 +801,35 @@ export const createCommand = new Command()
       const spinner = shouldShowSpinner() ? new Spinner() : null
       spinner?.start()
       try {
-        team = (team == null) ? getTeamKey() : team.toUpperCase()
-        if (!team) {
-          throw new ValidationError("Could not determine team key")
-        }
-
-        // For functions that need actual team IDs (like createIssue), get the ID
-        let teamId = await getTeamIdByKey(team)
-        if (interactive && !teamId) {
-          const teamIds = await searchTeamsByKeySubstring(team)
-          spinner?.stop()
-          teamId = await selectOption("Team", team, teamIds)
-          spinner?.start()
-        }
-        if (!teamId) {
-          throw new NotFoundError("Team", team)
+        // An explicit --team (key, name, or UUID) must resolve or error. Only
+        // the configured default, which the user did not type, may fall back
+        // to the interactive substring picker.
+        let teamId: string
+        if (team != null) {
+          const resolved = await resolveTeam(team)
+          teamId = resolved.id
+          team = resolved.key
+        } else {
+          team = getTeamKey()
+          if (!team) {
+            throw new ValidationError("Could not determine team key")
+          }
+          const found = await findTeam(team)
+          if (found) {
+            teamId = found.id
+          } else {
+            let picked: string | undefined
+            if (interactive) {
+              const teamIds = await searchTeamsByKeySubstring(team)
+              spinner?.stop()
+              picked = await selectOption("Team", team, teamIds)
+              spinner?.start()
+            }
+            if (!picked) {
+              throw new NotFoundError("Team", team)
+            }
+            teamId = picked
+          }
         }
         if (start && assignee === undefined) {
           assignee = "self"
diff --git a/src/commands/issue/issue-mine.ts b/src/commands/issue/issue-mine.ts
index 8429cbf5..6b1c9295 100644
--- a/src/commands/issue/issue-mine.ts
+++ b/src/commands/issue/issue-mine.ts
@@ -16,11 +16,13 @@ import {
   getCycleIdByNameOrNumber,
   getProjectIdByName,
   getProjectOptionsByName,
-  getTeamIdByKey,
   getTeamKey,
   isIssueBlocked,
   isLinearUuid,
+  ISSUE_STATE_TYPES,
   resolveMilestoneId,
+  resolveStateSelection,
+  resolveTeam,
   selectOption,
 } from "../../utils/linear.ts"
 import { openTeamAssigneeView } from "../../utils/actions.ts"
@@ -34,23 +36,16 @@ import {
 } from "../../utils/errors.ts"
 
 const SortType = new EnumType(["manual", "priority"])
-const StateType = new EnumType([
-  "triage",
-  "backlog",
-  "unstarted",
-  "started",
-  "completed",
-  "canceled",
-])
 
 export const mineCommand = new Command()
   .name("mine")
   .description("List your issues")
   .type("sort", SortType)
-  .type("state", StateType)
   .option(
-    "-s, --state <state:state>",
-    "Filter by issue state (can be repeated for multiple states)",
+    "-s, --state <state:string>",
+    `Filter by workflow state type (${
+      ISSUE_STATE_TYPES.join(", ")
+    }), name, or ID (can be repeated for multiple states)`,
     {
       default: ["unstarted"],
       collect: true,
@@ -69,7 +64,7 @@ export const mineCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Team to list issues for (if not your default team)",
+    "Team key, name, or ID to list issues for (if not your default team)",
   )
   .option(
     "--project <project:string>",
@@ -180,14 +175,17 @@ export const mineCommand = new Command()
         }
 
         const sort = resolveIssueSort(sortFlag)
-        const teamKey = team || getTeamKey()
+        // An explicit team may be a key, name, or UUID; keep the resolved
+        // team so --cycle can reuse its UUID. The configured default is a key.
+        const explicitTeam = team ? await resolveTeam(team) : undefined
+        const teamKey = explicitTeam?.key ?? getTeamKey()
         if (!teamKey) {
           throw new ValidationError(
             "No default team configured and no team scope provided",
             {
               suggestion: (await isInsideGitRepo())
-                ? "Use --team <key> to specify a team, or run `linear config` to link this repository to a team."
-                : "Use --team <key> to specify a team.",
+                ? "Use --team <key, name, or ID> to specify a team, or run `linear config` to link this repository to a team."
+                : "Use --team <key, name, or ID> to specify a team.",
             },
           )
         }
@@ -223,10 +221,7 @@ export const mineCommand = new Command()
 
         let cycleId: string | undefined
         if (cycle != null) {
-          const teamId = await getTeamIdByKey(teamKey)
-          if (!teamId) {
-            throw new NotFoundError("Team", teamKey)
-          }
+          const teamId = explicitTeam?.id ?? (await resolveTeam(teamKey)).id
           cycleId = await getCycleIdByNameOrNumber(cycle, teamId)
         }
 
@@ -266,9 +261,13 @@ export const mineCommand = new Command()
         const spinner = showSpinner ? new Spinner() : null
         spinner?.start()
 
+        const stateSelection = allStates
+          ? undefined
+          : await resolveStateSelection(stateArray, { teamKeys: [teamKey] })
+
         const result = await fetchIssuesForState(
           teamKey,
-          allStates ? undefined : stateArray,
+          stateSelection,
           undefined, // assignee — always self
           false, // unassigned
           false, // allAssignees
diff --git a/src/commands/issue/issue-query.ts b/src/commands/issue/issue-query.ts
index 63cb9a8c..0cdb0381 100644
--- a/src/commands/issue/issue-query.ts
+++ b/src/commands/issue/issue-query.ts
@@ -16,13 +16,17 @@ import {
   getCycleIdByNameOrNumber,
   getProjectIdByName,
   getProjectOptionsByName,
-  getTeamIdByKey,
   getTeamKeyWithSource,
   isIssueBlocked,
   isLinearUuid,
+  ISSUE_STATE_TYPES,
   resolveMilestoneId,
+  resolveStateSelection,
+  resolveTeam,
+  resolveTeams,
   searchIssuesByTerm,
   selectOption,
+  type StateSelection,
 } from "../../utils/linear.ts"
 import { pipeToUserPager, shouldUsePager } from "../../utils/pager.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
@@ -34,20 +38,11 @@ import {
 } from "../../utils/errors.ts"
 
 const SortType = new EnumType(["manual", "priority"])
-const StateType = new EnumType([
-  "triage",
-  "backlog",
-  "unstarted",
-  "started",
-  "completed",
-  "canceled",
-])
 
 export const queryCommand = new Command()
   .name("query")
   .description("Query issues with structured filters")
   .type("sort", SortType)
-  .type("state", StateType)
   .option(
     "--search <term:string>",
     "Full-text search term",
@@ -58,13 +53,15 @@ export const queryCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Filter by team key (can be repeated for multiple teams)",
+    "Filter by team key, name, or ID (can be repeated for multiple teams)",
     { collect: true },
   )
   .option("--all-teams", "Query across all teams")
   .option(
-    "-s, --state <state:state>",
-    "Filter by issue state (can be repeated for multiple states)",
+    "-s, --state <state:string>",
+    `Filter by workflow state type (${
+      ISSUE_STATE_TYPES.join(", ")
+    }), name, or ID (can be repeated for multiple states)`,
     { collect: true },
   )
   .option("--all-states", "Show issues from all states (this is the default)")
@@ -148,13 +145,11 @@ export const queryCommand = new Command()
     try {
       // --- Validation ---
 
-      const teamKeys = teamFlags
-        ? (Array.isArray(teamFlags) ? teamFlags.flat() : [teamFlags]).map((
-          t: string,
-        ) => t.toUpperCase())
+      const teamRefs = teamFlags
+        ? (Array.isArray(teamFlags) ? teamFlags.flat() : [teamFlags])
         : undefined
 
-      if (teamKeys && teamKeys.length > 0 && allTeams) {
+      if (teamRefs && teamRefs.length > 0 && allTeams) {
         throw new ValidationError(
           "Cannot use both --team and --all-teams flags",
         )
@@ -234,13 +229,19 @@ export const queryCommand = new Command()
 
       let resolvedTeamKeys: string[] | undefined
       let isMultiTeam = false
+      // The UUID of the single scoped team when `--team` was explicit; only
+      // `--cycle` needs it, and resolving the flag already fetched it.
+      let explicitTeamId: string | undefined
 
       if (allTeams) {
         resolvedTeamKeys = undefined
         isMultiTeam = true
-      } else if (teamKeys && teamKeys.length > 0) {
-        resolvedTeamKeys = teamKeys
-        isMultiTeam = teamKeys.length > 1
+      } else if (teamRefs && teamRefs.length > 0) {
+        // Keys, names, or UUIDs; downstream filters use the canonical keys.
+        const teams = await resolveTeams(teamRefs)
+        resolvedTeamKeys = teams.map((t) => t.key)
+        isMultiTeam = teams.length > 1
+        explicitTeamId = teams.length === 1 ? teams[0].id : undefined
       } else {
         const defaultTeam = getTeamKeyWithSource()
         if (!defaultTeam) {
@@ -248,13 +249,13 @@ export const queryCommand = new Command()
             "No default team configured and no team scope provided",
             {
               suggestion:
-                "Use --team <key> to specify a team, or --all-teams to query the whole workspace.",
+                "Use --team <key, name, or ID> to specify a team, or --all-teams to query the whole workspace.",
             },
           )
         }
         if (shouldShowDefaultTeamNote(defaultTeam.source)) {
           console.error(
-            `Note: using default team ${defaultTeam.key}. Pass --team <key> or --all-teams to be explicit.`,
+            `Note: using default team ${defaultTeam.key}. Pass --team <key, name, or ID> or --all-teams to be explicit.`,
           )
         }
         resolvedTeamKeys = [defaultTeam.key]
@@ -262,6 +263,18 @@ export const queryCommand = new Command()
 
       // --- Resolve entity IDs ---
 
+      // State names and IDs are looked up within the team scope, so this has
+      // to wait until the scope is known. Bare types need no lookup.
+      const stateSelection: StateSelection | undefined =
+        stateArray && stateArray.length > 0
+          ? await resolveStateSelection(
+            stateArray,
+            resolvedTeamKeys
+              ? { teamKeys: resolvedTeamKeys }
+              : { allTeams: true },
+          )
+          : undefined
+
       let projectId: string | undefined
       if (project != null) {
         projectId = await getProjectIdByName(project)
@@ -289,14 +302,12 @@ export const queryCommand = new Command()
             "--cycle requires a single team scope",
             {
               suggestion:
-                "Use --team <key> to specify exactly one team when filtering by cycle.",
+                "Use --team <key, name, or ID> to specify exactly one team when filtering by cycle.",
             },
           )
         }
-        const teamId = await getTeamIdByKey(resolvedTeamKeys[0])
-        if (!teamId) {
-          throw new NotFoundError("Team", resolvedTeamKeys[0])
-        }
+        const teamId = explicitTeamId ??
+          (await resolveTeam(resolvedTeamKeys[0])).id
         cycleId = await getCycleIdByNameOrNumber(cycle, teamId)
       }
 
@@ -330,7 +341,7 @@ export const queryCommand = new Command()
 
         const result = await searchIssuesByTerm(searchTerm, {
           teamKeys: resolvedTeamKeys,
-          state: stateArray,
+          state: stateSelection,
           assignee,
           unassigned,
           limit: limit === 0 ? 0 : limit,
@@ -368,7 +379,7 @@ export const queryCommand = new Command()
         const result = await fetchIssuesForQuery({
           teamKeys: resolvedTeamKeys,
           allTeams: allTeams === true,
-          state: stateArray,
+          state: stateSelection,
           assignee,
           unassigned,
           sort,
diff --git a/src/commands/issue/issue-start.ts b/src/commands/issue/issue-start.ts
index 1ae90272..f273be3c 100644
--- a/src/commands/issue/issue-start.ts
+++ b/src/commands/issue/issue-start.ts
@@ -53,7 +53,7 @@ export const startCommand = new Command()
       if (!resolvedId) {
         const result = await fetchIssuesForState(
           teamId,
-          ["unstarted"],
+          { types: ["unstarted"], stateIds: [] },
           undefined,
           unassigned,
           allAssignees,
diff --git a/src/commands/issue/issue-update.ts b/src/commands/issue/issue-update.ts
index 94324097..c538e2d5 100644
--- a/src/commands/issue/issue-update.ts
+++ b/src/commands/issue/issue-update.ts
@@ -10,11 +10,11 @@ import {
   getIssueLabelIdByNameForTeam,
   getIssueProjectId,
   getProjectIdByName,
-  getTeamIdByKey,
   getWorkflowStates,
   isLinearUuid,
   lookupUserId,
   resolveMilestoneId,
+  resolveTeam,
   resolveWorkflowState,
   workflowStateNotFoundError,
 } from "../../utils/linear.ts"
@@ -79,7 +79,7 @@ export const updateCommand = new Command()
   )
   .option(
     "--team <team:string>",
-    "Team associated with the issue (if not your default team)",
+    "Team (key, name, or ID) to move the issue to",
   )
   .option(
     "--project <project:string>",
@@ -211,22 +211,17 @@ export const updateCommand = new Command()
         const spinner = shouldShowSpinner() ? new Spinner() : null
         spinner?.start()
 
-        // Extract team from issue ID if not provided
-        let teamKey = team
-        if (!teamKey) {
-          teamKey = getTeamKeyFromIssueIdentifier(issueId)
-        }
-        if (!teamKey) {
+        // An explicit --team may be a key, name, or UUID; otherwise the team
+        // is the one in the issue identifier.
+        const teamRef = team ?? getTeamKeyFromIssueIdentifier(issueId)
+        if (!teamRef) {
           throw new ValidationError(
             "Could not determine team key from issue ID",
           )
         }
 
-        // Convert team key to team ID for some operations
-        const teamId = await getTeamIdByKey(teamKey)
-        if (!teamId) {
-          throw new NotFoundError("Team", teamKey)
-        }
+        // The mutation needs the UUID; state and label lookups use the key.
+        const { id: teamId, key: teamKey } = await resolveTeam(teamRef)
 
         let stateId: string | undefined
         if (state != null) {
diff --git a/src/commands/label/label-create.ts b/src/commands/label/label-create.ts
index 58a412e5..8fe29a47 100644
--- a/src/commands/label/label-create.ts
+++ b/src/commands/label/label-create.ts
@@ -2,14 +2,9 @@ import { Command } from "@cliffy/command"
 import { Input, Select } from "@cliffy/prompt"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
-import { getAllTeams, getTeamIdByKey, getTeamKey } from "../../utils/linear.ts"
+import { getAllTeams, getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
-import {
-  CliError,
-  handleError,
-  NotFoundError,
-  ValidationError,
-} from "../../utils/errors.ts"
+import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
 
 const CreateIssueLabel = gql(`
   mutation CreateIssueLabel($input: IssueLabelCreateInput!) {
@@ -53,8 +48,8 @@ export const createCommand = new Command()
   )
   .option("-d, --description <description:string>", "Label description")
   .option(
-    "-t, --team <teamKey:string>",
-    "Team key for team-specific label (omit for workspace label)",
+    "-t, --team <team:string>",
+    "Team key, name, or ID for a team-specific label (omit for workspace label)",
   )
   .option(
     "-i, --interactive",
@@ -183,10 +178,7 @@ export const createCommand = new Command()
       // Build input
       let teamId: string | undefined
       if (teamKey) {
-        teamId = await getTeamIdByKey(teamKey.toUpperCase())
-        if (!teamId) {
-          throw new NotFoundError("Team", teamKey)
-        }
+        teamId = (await resolveTeam(teamKey)).id
       }
 
       const input = {
diff --git a/src/commands/label/label-delete.ts b/src/commands/label/label-delete.ts
index 3f8325a0..25a9174b 100644
--- a/src/commands/label/label-delete.ts
+++ b/src/commands/label/label-delete.ts
@@ -2,7 +2,7 @@ import { Command } from "@cliffy/command"
 import { Confirm, Select } from "@cliffy/prompt"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
-import { getTeamKey } from "../../utils/linear.ts"
+import { getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import {
   CliError,
@@ -142,16 +142,19 @@ export const deleteCommand = new Command()
   .description("Delete an issue label")
   .arguments("<nameOrId:string>")
   .option(
-    "-t, --team <teamKey:string>",
-    "Team key to disambiguate labels with same name",
+    "-t, --team <team:string>",
+    "Team key, name, or ID to disambiguate labels with the same name",
   )
   .option("-f, --force", "Skip confirmation prompt")
   .action(async ({ team: teamKey, force }, nameOrId) => {
     try {
       const client = getGraphQLClient()
 
-      // Use configured team if not specified
-      const effectiveTeamKey = teamKey || getTeamKey()
+      // An explicit team may be a key, name, or ID; labels are matched on the
+      // canonical key. The configured default is already a key.
+      const effectiveTeamKey = teamKey
+        ? (await resolveTeam(teamKey)).key
+        : getTeamKey()
 
       // Resolve label
       const label = await resolveLabelId(client, nameOrId, effectiveTeamKey)
diff --git a/src/commands/label/label-list.ts b/src/commands/label/label-list.ts
index 6681d36d..00192ea9 100644
--- a/src/commands/label/label-list.ts
+++ b/src/commands/label/label-list.ts
@@ -1,10 +1,13 @@
 import { Command } from "@cliffy/command"
 import { unicodeWidth } from "@std/cli"
 import { gql } from "../../__codegen__/gql.ts"
-import type { GetIssueLabelsQuery } from "../../__codegen__/graphql.ts"
+import type {
+  GetIssueLabelsQuery,
+  IssueLabelFilter,
+} from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { padDisplay } from "../../utils/display.ts"
-import { getTeamKey } from "../../utils/linear.ts"
+import { getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError } from "../../utils/errors.ts"
 
@@ -35,8 +38,8 @@ export const listCommand = new Command()
   .name("list")
   .description("List issue labels")
   .option(
-    "--team <teamKey:string>",
-    "Filter by team (e.g., TC). Shows team-specific labels only.",
+    "--team <team:string>",
+    "Filter by team key, name, or ID (e.g., TC). Shows that team's labels plus workspace labels.",
   )
   .option(
     "--workspace",
@@ -57,17 +60,17 @@ export const listCommand = new Command()
       const client = getGraphQLClient()
 
       // Build filter based on options
-      // deno-lint-ignore no-explicit-any
-      let filter: any = {}
+      let filter: IssueLabelFilter = {}
 
       if (workspace) {
         // Only workspace labels (no team)
         filter = { team: { null: true } }
       } else if (teamKey) {
         // Only labels for a specific team (includes workspace labels)
+        const team = await resolveTeam(teamKey)
         filter = {
           or: [
-            { team: { key: { eq: teamKey.toUpperCase() } } },
+            { team: { key: { eq: team.key } } },
             { team: { null: true } },
           ],
         }
diff --git a/src/commands/project/project-create.ts b/src/commands/project/project-create.ts
index d88ee121..6429a96d 100644
--- a/src/commands/project/project-create.ts
+++ b/src/commands/project/project-create.ts
@@ -7,9 +7,9 @@ import type { GraphQLClient } from "graphql-request"
 import {
   getAllTeams,
   getProjectLabelIdByName,
-  getTeamIdByKey,
   getTeamKey,
   lookupUserId,
+  resolveTeams,
 } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import {
@@ -178,7 +178,7 @@ export const createCommand = new Command()
   )
   .option(
     "-t, --team <team:string>",
-    "Team key (required, can be repeated for multiple teams)",
+    "Team key, name, or ID (required, can be repeated for multiple teams)",
     { collect: true },
   )
   .option(
@@ -389,14 +389,7 @@ export const createCommand = new Command()
         }
 
         // Resolve team IDs
-        const teamIds: string[] = []
-        for (const teamKey of teams) {
-          const teamId = await getTeamIdByKey(teamKey.toUpperCase())
-          if (!teamId) {
-            throw new NotFoundError("Team", teamKey)
-          }
-          teamIds.push(teamId)
-        }
+        const teamIds = (await resolveTeams(teams)).map((t) => t.id)
 
         // Build input - resolve all optional fields first
         let leadId: string | undefined
diff --git a/src/commands/project/project-list.ts b/src/commands/project/project-list.ts
index 64b5228f..0f215d12 100644
--- a/src/commands/project/project-list.ts
+++ b/src/commands/project/project-list.ts
@@ -9,7 +9,7 @@ import type {
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { getTimeAgo, padDisplay } from "../../utils/display.ts"
 import { LINEAR_WEB_BASE_URL } from "../../const.ts"
-import { getTeamKey } from "../../utils/linear.ts"
+import { getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { getOption } from "../../config.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError, ValidationError } from "../../utils/errors.ts"
@@ -62,7 +62,7 @@ const GetProjects = gql(`
 export const listCommand = new Command()
   .name("list")
   .description("List projects")
-  .option("--team <team:string>", "Filter by team key")
+  .option("--team <team:string>", "Filter by team key, name, or ID")
   .option("--all-teams", "Show projects from all teams")
   .option("--status <status:string>", "Filter by status name")
   .option("-w, --web", "Open in web browser")
@@ -70,31 +70,37 @@ export const listCommand = new Command()
   .option("-j, --json", "Output as JSON")
   .action(async ({ team, allTeams, status, web, app, json }) => {
     if (web || app) {
-      let workspace = getOption("workspace")
-      if (!workspace) {
-        // Get workspace from viewer if not configured
-        const client = getGraphQLClient()
-        const viewerQuery = gql(`
-          query GetViewer {
-            viewer {
-              organization {
-                urlKey
+      try {
+        let workspace = getOption("workspace")
+        if (!workspace) {
+          // Get workspace from viewer if not configured
+          const client = getGraphQLClient()
+          const viewerQuery = gql(`
+            query GetViewer {
+              viewer {
+                organization {
+                  urlKey
+                }
               }
             }
-          }
-        `)
-        const result = await client.request(viewerQuery)
-        workspace = result.viewer.organization.urlKey
-      }
+          `)
+          const result = await client.request(viewerQuery)
+          workspace = result.viewer.organization.urlKey
+        }
 
-      // Determine team to filter by for URL construction
-      const teamKey = allTeams ? null : (team?.toUpperCase() || getTeamKey())
-      const url = teamKey
-        ? `${LINEAR_WEB_BASE_URL}/${workspace}/team/${teamKey}/projects/all`
-        : `${LINEAR_WEB_BASE_URL}/${workspace}/projects/all`
-      const destination = app ? "Linear.app" : "web browser"
-      console.log(`Opening ${url} in ${destination}`)
-      await open(url, app ? { app: { name: "Linear" } } : undefined)
+        // Determine team to filter by for URL construction
+        const teamKey = allTeams
+          ? null
+          : (team ? (await resolveTeam(team)).key : getTeamKey())
+        const url = teamKey
+          ? `${LINEAR_WEB_BASE_URL}/${workspace}/team/${teamKey}/projects/all`
+          : `${LINEAR_WEB_BASE_URL}/${workspace}/projects/all`
+        const destination = app ? "Linear.app" : "web browser"
+        console.log(`Opening ${url} in ${destination}`)
+        await open(url, app ? { app: { name: "Linear" } } : undefined)
+      } catch (error) {
+        handleError(error, "Failed to open projects")
+      }
       return
     }
     const { Spinner } = await import("@std/cli/unstable-spinner")
@@ -111,7 +117,9 @@ export const listCommand = new Command()
       }
 
       // Determine team to filter by
-      const teamKey = allTeams ? null : (team?.toUpperCase() || getTeamKey())
+      const teamKey = allTeams
+        ? null
+        : (team ? (await resolveTeam(team)).key : getTeamKey())
 
       let filter = {}
       if (teamKey) {
diff --git a/src/commands/project/project-update.ts b/src/commands/project/project-update.ts
index 28595177..e9cfc9c0 100644
--- a/src/commands/project/project-update.ts
+++ b/src/commands/project/project-update.ts
@@ -4,9 +4,9 @@ import type { ProjectUpdateInput } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import {
   getProjectLabelIdByName,
-  getTeamIdByKey,
   lookupUserId,
   resolveProjectId,
+  resolveTeams,
 } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import {
@@ -87,7 +87,7 @@ export const updateCommand = new Command()
   .option("--target-date <targetDate:string>", "Target date (YYYY-MM-DD)")
   .option(
     "-t, --team <team:string>",
-    "Team key (can be repeated for multiple teams)",
+    "Team key, name, or ID (can be repeated for multiple teams)",
     { collect: true },
   )
   .option(
@@ -205,16 +205,7 @@ export const updateCommand = new Command()
         }
 
         if (teams && teams.length > 0) {
-          const teamIds: string[] = []
-          for (const teamKey of teams) {
-            const teamId = await getTeamIdByKey(teamKey.toUpperCase())
-            if (!teamId) {
-              spinner?.stop()
-              throw new NotFoundError("Team", teamKey)
-            }
-            teamIds.push(teamId)
-          }
-          input.teamIds = teamIds
+          input.teamIds = (await resolveTeams(teams)).map((t) => t.id)
         }
 
         if (labels && labels.length > 0) {
diff --git a/src/commands/team/team-delete.ts b/src/commands/team/team-delete.ts
index 925c2e38..c645e8f0 100644
--- a/src/commands/team/team-delete.ts
+++ b/src/commands/team/team-delete.ts
@@ -2,7 +2,7 @@ import { Command } from "@cliffy/command"
 import { Confirm, Select } from "@cliffy/prompt"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
-import { getAllTeams, getTeamIdByKey } from "../../utils/linear.ts"
+import { getAllTeams, resolveTeam } from "../../utils/linear.ts"
 import {
   CliError,
   handleError,
@@ -30,21 +30,18 @@ const GetTeamIssuesForMove = gql(`
 export const deleteCommand = new Command()
   .name("delete")
   .description("Delete a Linear team")
-  .arguments("<teamKey:string>")
+  .arguments("<team:string>")
   .option(
     "--move-issues <targetTeam:string>",
-    "Move all issues to another team before deletion",
+    "Move all issues to another team (key, name, or ID) before deletion",
   )
   .option("-y, --force", "Skip confirmation prompt")
   .action(async ({ moveIssues, force }, teamKey) => {
     try {
       const client = getGraphQLClient()
 
-      // Resolve the team ID from the key
-      const teamId = await getTeamIdByKey(teamKey.toUpperCase())
-      if (!teamId) {
-        throw new NotFoundError("Team", teamKey)
-      }
+      // Resolve the team ID from the key, name, or ID
+      const teamId = (await resolveTeam(teamKey)).id
 
       // Get team details for confirmation message
       const teamDetailsQuery = gql(`
@@ -108,10 +105,7 @@ export const deleteCommand = new Command()
         await moveIssuesToTeam(client, teamId, targetTeamId, issueCount)
       } else if (issueCount > 0 && moveIssues) {
         // Resolve the target team
-        const targetTeamId = await getTeamIdByKey(moveIssues.toUpperCase())
-        if (!targetTeamId) {
-          throw new NotFoundError("Target team", moveIssues)
-        }
+        const targetTeamId = (await resolveTeam(moveIssues)).id
 
         if (targetTeamId === teamId) {
           throw new ValidationError("Cannot move issues to the same team")
diff --git a/src/commands/team/team-members.ts b/src/commands/team/team-members.ts
index 89a15533..b62d39db 100644
--- a/src/commands/team/team-members.ts
+++ b/src/commands/team/team-members.ts
@@ -1,28 +1,33 @@
 import { Command } from "@cliffy/command"
-import { getTeamKey, getTeamMembers } from "../../utils/linear.ts"
+import { getTeamKey, getTeamMembers, resolveTeam } from "../../utils/linear.ts"
 import { printMembers } from "../../utils/member-display.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError, ValidationError } from "../../utils/errors.ts"
 
 export const membersCommand = new Command()
   .name("members")
-  .description("List team members")
-  .arguments("[teamKey:string]")
+  .description("List team members (team by key, name, or ID)")
+  .arguments("[team:string]")
   .option("-a, --all", "Include inactive members")
   .option(
     "-j, --json",
     "Output as JSON; a member's url mentions them when pasted into Markdown",
   )
-  .action(async ({ all, json }, teamKey?: string) => {
+  .action(async ({ all, json }, team?: string) => {
     const showSpinner = !json && shouldShowSpinner()
     let spinner: { start: () => void; stop: () => void } | null = null
 
     try {
-      const resolvedTeamKey = teamKey || getTeamKey()
+      const resolvedTeamKey = team
+        ? (await resolveTeam(team)).key
+        : getTeamKey()
       if (!resolvedTeamKey) {
         throw new ValidationError(
           "Could not determine team key from directory name",
-          { suggestion: "Please specify a team key as an argument." },
+          {
+            suggestion:
+              "Please specify a team key, name, or ID as an argument.",
+          },
         )
       }
 
diff --git a/src/commands/team/team-states.ts b/src/commands/team/team-states.ts
index 550bfa23..cd68e13a 100644
--- a/src/commands/team/team-states.ts
+++ b/src/commands/team/team-states.ts
@@ -1,25 +1,34 @@
 import { Command } from "@cliffy/command"
 import { unicodeWidth } from "@std/cli"
-import { getTeamKey, getWorkflowStates } from "../../utils/linear.ts"
+import {
+  getTeamKey,
+  getWorkflowStates,
+  resolveTeam,
+} from "../../utils/linear.ts"
 import { padDisplay } from "../../utils/display.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError, ValidationError } from "../../utils/errors.ts"
 
 export const statesCommand = new Command()
   .name("states")
-  .description("List workflow states for a team")
-  .arguments("[teamKey:string]")
+  .description("List workflow states for a team (by key, name, or ID)")
+  .arguments("[team:string]")
   .option("-j, --json", "Output as JSON")
-  .action(async ({ json }, teamKey?: string) => {
+  .action(async ({ json }, team?: string) => {
     const showSpinner = !json && shouldShowSpinner()
     let spinner: { start: () => void; stop: () => void } | null = null
 
     try {
-      const resolvedTeamKey = teamKey || getTeamKey()
+      const resolvedTeamKey = team
+        ? (await resolveTeam(team)).key
+        : getTeamKey()
       if (!resolvedTeamKey) {
         throw new ValidationError(
           "Could not determine team key from directory name",
-          { suggestion: "Please specify a team key as an argument." },
+          {
+            suggestion:
+              "Please specify a team key, name, or ID as an argument.",
+          },
         )
       }
 
diff --git a/src/utils/linear.ts b/src/utils/linear.ts
index 375ee72c..308d4ea8 100644
--- a/src/utils/linear.ts
+++ b/src/utils/linear.ts
@@ -9,6 +9,7 @@ import type {
   GetOrganizationMembersQuery,
   GetProjectsForTeamQuery,
   GetTeamMembersQuery,
+  GetWorkflowStatesInScopeQuery,
   IssueFilter,
   IssueSortInput,
   PaginationOrderBy,
@@ -351,6 +352,194 @@ export function workflowStateNotFoundError(
   )
 }
 
+/**
+ * The workflow state types `issue query --state` / `issue mine --state` accept
+ * as bare type tokens. Matched exactly (lowercase), so `Backlog` is a state
+ * name lookup while `backlog` selects every state of that type.
+ */
+export const ISSUE_STATE_TYPES = [
+  "triage",
+  "backlog",
+  "unstarted",
+  "started",
+  "completed",
+  "canceled",
+] as const
+
+export type StateScope =
+  | { teamKeys: readonly string[] }
+  | { allTeams: true }
+
+/** A `--state` selection after names and IDs have been resolved to state IDs. */
+export type StateSelection = { types: string[]; stateIds: string[] }
+
+function isIssueStateType(value: string): boolean {
+  return (ISSUE_STATE_TYPES as readonly string[]).includes(value)
+}
+
+type ScopedWorkflowState = {
+  id: string
+  name: string
+  type: string
+  team: { key: string }
+}
+
+async function getWorkflowStatesInScope(
+  scope: StateScope,
+): Promise<ScopedWorkflowState[]> {
+  const query = gql(/* GraphQL */ `
+    query GetWorkflowStatesInScope(
+      $filter: WorkflowStateFilter
+      $first: Int
+      $after: String
+    ) {
+      workflowStates(filter: $filter, first: $first, after: $after) {
+        nodes {
+          id
+          name
+          type
+          team {
+            key
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  `)
+  const filter = "allTeams" in scope
+    ? undefined
+    : { team: { key: { in: [...scope.teamKeys] } } }
+
+  const client = getGraphQLClient()
+  const states: ScopedWorkflowState[] = []
+  let after: string | null | undefined = undefined
+  let hasNextPage = true
+  while (hasNextPage) {
+    const result: GetWorkflowStatesInScopeQuery = await client.request(query, {
+      filter,
+      first: 250,
+      after,
+    })
+    states.push(...result.workflowStates.nodes)
+    hasNextPage = result.workflowStates.pageInfo.hasNextPage
+    const endCursor = result.workflowStates.pageInfo.endCursor
+    // A page that claims to continue but offers no new cursor would refetch
+    // itself forever; treat it as the malformed response it is.
+    if (hasNextPage && (endCursor == null || endCursor === after)) {
+      throw new CliError(
+        "Linear reported more workflow states but returned no new pagination cursor",
+        { suggestion: "Retry the command." },
+      )
+    }
+    after = endCursor
+  }
+  return states
+}
+
+/**
+ * Turn `--state` values into a selection of state types and state IDs.
+ *
+ * A value equal to one of ISSUE_STATE_TYPES is a type. Anything else is a
+ * workflow state name (case-insensitive, matching every same-named state in the
+ * scope, which may span several teams) or a state UUID, and must exist in the
+ * scope: a state from a team outside the scope would otherwise silently match
+ * nothing. Type-only input makes no API call.
+ */
+export async function resolveStateSelection(
+  values: readonly string[],
+  scope: StateScope,
+): Promise<StateSelection> {
+  const types: string[] = []
+  const lookups: string[] = []
+  for (const value of values) {
+    if (value.trim() === "") {
+      throw new ValidationError("--state value is empty", {
+        suggestion: `Pass a state type (${
+          ISSUE_STATE_TYPES.join(", ")
+        }), name, or ID.`,
+      })
+    }
+    if (isIssueStateType(value)) {
+      if (!types.includes(value)) types.push(value)
+    } else if (!lookups.includes(value)) {
+      lookups.push(value)
+    }
+  }
+  if (lookups.length === 0) {
+    return { types, stateIds: [] }
+  }
+
+  const states = await getWorkflowStatesInScope(scope)
+  const stateIds: string[] = []
+  for (const value of lookups) {
+    // Linear returns lowercase UUIDs; accept any casing on input, as
+    // isLinearUuid already does.
+    const wanted = value.toLowerCase()
+    const matches = isLinearUuid(value)
+      ? states.filter((s) => s.id.toLowerCase() === wanted)
+      : states.filter((s) => s.name.toLowerCase() === wanted)
+    if (matches.length === 0) {
+      throw stateNotFoundInScopeError(value, scope, states)
+    }
+    for (const match of matches) {
+      if (!stateIds.includes(match.id)) stateIds.push(match.id)
+    }
+  }
+  return { types, stateIds }
+}
+
+function stateNotFoundInScopeError(
+  value: string,
+  scope: StateScope,
+  states: readonly ScopedWorkflowState[],
+): NotFoundError {
+  const singleTeam = !("allTeams" in scope) && scope.teamKeys.length === 1
+  const where = "allTeams" in scope
+    ? "any team"
+    : `team${scope.teamKeys.length === 1 ? "" : "s"} ${
+      scope.teamKeys.join(", ")
+    }`
+  const listed = states
+    .slice()
+    .sort((a, b) =>
+      a.team.key.localeCompare(b.team.key) || a.name.localeCompare(b.name)
+    )
+    .map((s) =>
+      singleTeam
+        ? `${JSON.stringify(s.name)} (${s.type})`
+        : `${JSON.stringify(s.name)} (${s.type}, ${s.team.key})`
+    )
+  const valid = listed.length > 0 ? `Valid states: ${listed.join(", ")}. ` : ""
+  return new NotFoundError("Workflow state", `'${value}' in ${where}`, {
+    suggestion: `${valid}State types: ${
+      ISSUE_STATE_TYPES.join(", ")
+    }. Run \`linear team states <team>\` to list a team's states.`,
+  })
+}
+
+/**
+ * The GraphQL `state` filter for a selection. Type-only selections keep the
+ * `{ type: { in } }` shape the CLI has always sent.
+ */
+export function workflowStateFilter(
+  selection: StateSelection,
+): IssueFilter["state"] {
+  const { types, stateIds } = selection
+  if (types.length > 0 && stateIds.length > 0) {
+    return { or: [{ type: { in: types } }, { id: { in: stateIds } }] }
+  }
+  if (stateIds.length > 0) {
+    return { id: { in: stateIds } }
+  }
+  if (types.length > 0) {
+    return { type: { in: types } }
+  }
+  throw new ValidationError("--state selection is empty")
+}
+
 export async function updateIssueState(
   issueId: string,
   stateId: string,
@@ -748,7 +937,7 @@ function getIssueSortPayload(
 
 export async function fetchIssuesForState(
   teamKey: string,
-  state: string[] | undefined,
+  state: StateSelection | undefined,
   assignee?: string,
   unassigned = false,
   allAssignees = false,
@@ -769,7 +958,7 @@ export async function fetchIssuesForState(
   }
 
   if (state) {
-    filter.state = { type: { in: state } }
+    filter.state = workflowStateFilter(state)
   }
 
   if (unassigned) {
@@ -1032,7 +1221,7 @@ export type FetchedQueryIssuePayload = {
 export interface FetchIssuesForQueryOptions {
   teamKeys?: string[]
   allTeams?: boolean
-  state?: string[]
+  state?: StateSelection
   assignee?: string
   unassigned?: boolean
   sort?: "manual" | "priority"
@@ -1064,8 +1253,8 @@ export async function fetchIssuesForQuery(
     }
   }
 
-  if (options.state && options.state.length > 0) {
-    filter.state = { type: { in: options.state } }
+  if (options.state) {
+    filter.state = workflowStateFilter(options.state)
   }
 
   if (options.unassigned) {
@@ -1282,7 +1471,7 @@ export type FetchedIssueSearchPayload = {
 export interface SearchIssuesByTermOptions {
   teamKey?: string
   teamKeys?: string[]
-  state?: string[]
+  state?: StateSelection
   assignee?: string
   unassigned?: boolean
   limit?: number
@@ -1315,8 +1504,8 @@ export async function searchIssuesByTerm(
     filter.team = { key: { eq: options.teamKey } }
   }
 
-  if (options.state != null && options.state.length > 0) {
-    filter.state = { type: { in: options.state } }
+  if (options.state != null) {
+    filter.state = workflowStateFilter(options.state)
   }
 
   if (options.unassigned) {
@@ -1547,21 +1736,140 @@ export async function getProjectsForTeam(
   )
 }
 
-export async function getTeamIdByKey(
-  team: string,
-): Promise<string | undefined> {
+export type ResolvedTeam = { id: string; key: string; name: string }
+
+/**
+ * Look up a team by key, name, or UUID in one round trip. Returns undefined
+ * when nothing matches; use [[resolveTeam]] when a miss should throw.
+ *
+ * Precedence is key, then UUID, then name, and it is applied client-side so it
+ * does not depend on what shapes Linear allows a key to take: a reference that
+ * equals one team's key and another team's name always means the key. Keys and
+ * names match case-insensitively; the returned `key` is the server's canonical
+ * (uppercase) form, so callers never need to normalize user input themselves.
+ */
+export async function findTeam(
+  reference: string,
+): Promise<ResolvedTeam | undefined> {
+  if (reference.trim() === "") {
+    throw new ValidationError("Team reference is empty", {
+      suggestion: "Pass a team key, name, or ID, e.g. --team ENG.",
+    })
+  }
   const client = getGraphQLClient()
   const query = gql(/* GraphQL */ `
-    query GetTeamIdByKey($team: String!) {
-      teams(filter: { key: { eq: $team } }) {
+    query ResolveTeam($reference: String!, $id: ID, $isUuid: Boolean!) {
+      teams(
+        filter: {
+          or: [
+            { key: { eqIgnoreCase: $reference } }
+            { name: { eqIgnoreCase: $reference } }
+          ]
+        }
+      ) {
+        nodes {
+          id
+          key
+          name
+        }
+      }
+      teamById: teams(filter: { id: { eq: $id } }) @include(if: $isUuid) {
         nodes {
           id
+          key
+          name
         }
       }
     }
   `)
-  const data = await client.request(query, { team })
-  return data.teams?.nodes[0]?.id
+  const isUuid = isLinearUuid(reference)
+  const data = await client.request(query, {
+    reference,
+    id: isUuid ? reference : null,
+    isUuid,
+  })
+
+  const wanted = reference.toLowerCase()
+  const candidates = data.teams.nodes
+  for (const team of candidates) {
+    assertTeamShape(team)
+  }
+  const byKey = candidates.find((t) => t.key.toLowerCase() === wanted)
+  if (byKey) return byKey
+
+  const byId = data.teamById?.nodes[0]
+  if (byId) {
+    assertTeamShape(byId)
+    return byId
+  }
+
+  const byName = candidates.filter((t) => t.name.toLowerCase() === wanted)
+  if (byName.length > 1) {
+    throw new ValidationError(
+      `Team name "${reference}" is ambiguous: ${
+        byName.map(formatTeamOption).join(", ")
+      }`,
+      { suggestion: "Use the team key instead of the name." },
+    )
+  }
+  return byName[0]
+}
+
+// The GraphQL client does not validate responses at runtime. A team without a
+// string key or name is a malformed response (or a test mock missing fields),
+// and the precedence logic above would otherwise crash on it with a TypeError.
+function assertTeamShape(team: { id: string; key: string; name: string }) {
+  if (typeof team.key !== "string" || typeof team.name !== "string") {
+    throw new CliError(
+      `Malformed team in API response: ${JSON.stringify(team)}`,
+    )
+  }
+}
+
+function formatTeamOption(team: { key: string; name: string }): string {
+  return `${team.key} (${team.name})`
+}
+
+/**
+ * Resolve a team reference (key, name, or UUID) or throw a NotFoundError whose
+ * suggestion lists every valid team key.
+ */
+export async function resolveTeam(reference: string): Promise<ResolvedTeam> {
+  const team = await findTeam(reference)
+  if (team) return team
+  throw await teamNotFoundError(reference)
+}
+
+/**
+ * Resolve several team references in parallel, keeping input order and
+ * dropping duplicates that resolve to the same team (e.g. `ENG` and `eng`).
+ */
+export async function resolveTeams(
+  references: readonly string[],
+): Promise<ResolvedTeam[]> {
+  const resolved = await Promise.all(references.map(resolveTeam))
+  const seen = new Set<string>()
+  return resolved.filter((team) => {
+    if (seen.has(team.id)) return false
+    seen.add(team.id)
+    return true
+  })
+}
+
+export async function teamNotFoundError(
+  reference: string,
+): Promise<NotFoundError> {
+  const teams = await getAllTeams()
+  const suggestion = teams.length > 0
+    ? `Valid team keys: ${
+      teams
+        .slice()
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .map(formatTeamOption)
+        .join(", ")
+    }. Run \`linear team list\` to see all teams.`
+    : "This workspace has no teams you can access."
+  return new NotFoundError("Team", reference, { suggestion })
 }
 
 export async function searchTeamsByKeySubstring(
diff --git a/test/commands/cycle/__snapshots__/cycle-list.test.ts.snap b/test/commands/cycle/__snapshots__/cycle-list.test.ts.snap
index 33a2e093..2a7b990c 100644
--- a/test/commands/cycle/__snapshots__/cycle-list.test.ts.snap
+++ b/test/commands/cycle/__snapshots__/cycle-list.test.ts.snap
@@ -11,9 +11,9 @@ Description:
 
 Options:
 
-  -h, --help          - Show this help.                      
-  --team      <team>  - Team key (defaults to current team)  
-  -j, --json          - Output as JSON                       
+  -h, --help          - Show this help.                                   
+  --team      <team>  - Team key, name, or ID (defaults to current team)  
+  -j, --json          - Output as JSON                                    
 
 "
 stderr:
@@ -126,3 +126,29 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Cycle List Command - By Team Name 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "name": "Sprint 1",
+      "startsAt": "2026-01-01T00:00:00.000Z",
+      "endsAt": "2026-01-15T00:00:00.000Z",
+      "completedAt": null,
+      "isActive": false,
+      "isFuture": false,
+      "isPast": true,
+      "id": "cycle-1",
+      "number": 1
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
diff --git a/test/commands/cycle/__snapshots__/cycle-view.test.ts.snap b/test/commands/cycle/__snapshots__/cycle-view.test.ts.snap
index 7ad07038..6926fc32 100644
--- a/test/commands/cycle/__snapshots__/cycle-view.test.ts.snap
+++ b/test/commands/cycle/__snapshots__/cycle-view.test.ts.snap
@@ -11,9 +11,9 @@ Description:
 
 Options:
 
-  -h, --help          - Show this help.                      
-  --team      <team>  - Team key (defaults to current team)  
-  -j, --json          - Output as JSON                       
+  -h, --help          - Show this help.                                   
+  --team      <team>  - Team key, name, or ID (defaults to current team)  
+  -j, --json          - Output as JSON                                    
 
 "
 stderr:
diff --git a/test/commands/cycle/cycle-list.test.ts b/test/commands/cycle/cycle-list.test.ts
index 5729367f..3f579fc1 100644
--- a/test/commands/cycle/cycle-list.test.ts
+++ b/test/commands/cycle/cycle-list.test.ts
@@ -25,11 +25,11 @@ await cliffySnapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
+        queryName: "ResolveTeam",
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -109,11 +109,11 @@ await cliffySnapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
+        queryName: "ResolveTeam",
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -151,8 +151,14 @@ await cliffySnapshotTest({
 })
 
 const TEAM_LOOKUP = {
-  queryName: "GetTeamIdByKey",
-  response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+  queryName: "ResolveTeam",
+  response: {
+    data: {
+      teams: {
+        nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+      },
+    },
+  },
 }
 
 function cycle(
@@ -343,3 +349,45 @@ Deno.test("Cycle List Command - errors on inconsistent pagination", async () =>
   assertEquals(exited, true)
   assertStringIncludes(errorLogs.join("\n"), "no pagination cursor")
 })
+
+// --team accepts a name; the cycles query gets the resolved UUID.
+await cliffySnapshotTest({
+  name: "Cycle List Command - By Team Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "Engineering", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      { ...TEAM_LOOKUP, variables: { reference: "Engineering" } },
+      {
+        queryName: "GetTeamCycles",
+        variables: { teamId: "team-eng-id", first: 100, after: undefined },
+        response: {
+          data: {
+            team: {
+              id: "team-eng-id",
+              name: "Engineering",
+              cycles: {
+                nodes: [cycle({ id: "cycle-1", number: 1, name: "Sprint 1" })],
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await listCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/cycle/cycle-view.test.ts b/test/commands/cycle/cycle-view.test.ts
index c9fe0268..bdba3f95 100644
--- a/test/commands/cycle/cycle-view.test.ts
+++ b/test/commands/cycle/cycle-view.test.ts
@@ -23,11 +23,11 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
+        queryName: "ResolveTeam",
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -139,11 +139,11 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
+        queryName: "ResolveTeam",
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -225,11 +225,11 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
+        queryName: "ResolveTeam",
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -326,8 +326,14 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetTeamCyclesForLookup",
diff --git a/test/commands/document/__snapshots__/document-create.test.ts.snap b/test/commands/document/__snapshots__/document-create.test.ts.snap
index d7809df9..0f99d44d 100644
--- a/test/commands/document/__snapshots__/document-create.test.ts.snap
+++ b/test/commands/document/__snapshots__/document-create.test.ts.snap
@@ -23,7 +23,7 @@ Options:
   --project           <project>     - Attach to project (UUID, slug ID, or name)                                        
   --issue             <issue>       - Attach to issue (identifier like TC-123)                                          
   --initiative        <initiative>  - Attach to initiative (UUID, slug ID, or name)                                     
-  --team              <team>        - Attach to team (key); with --cycle, scopes the cycle lookup instead               
+  --team              <team>        - Attach to team (key, name, or ID); with --cycle, scopes the cycle lookup instead  
   --cycle             <cycle>       - Attach to cycle: name, number, 'active'/'now', 'next', 'previous', or a relative  
                                       offset like +1 (team from --team or config)                                       
   --release           <release>     - Attach to release (UUID, name, or version)                                        
diff --git a/test/commands/document/__snapshots__/document-list.test.ts.snap b/test/commands/document/__snapshots__/document-list.test.ts.snap
index 2c47f01f..339f48a6 100644
--- a/test/commands/document/__snapshots__/document-list.test.ts.snap
+++ b/test/commands/document/__snapshots__/document-list.test.ts.snap
@@ -15,7 +15,7 @@ Options:
   --project     <project>     - Filter by project (UUID, slug ID, or name)                                                     
   --issue       <issue>       - Filter by issue (identifier like TC-123)                                                       
   --initiative  <initiative>  - Filter by initiative (UUID, slug ID, or name)                                                  
-  --team        <team>        - Filter by team (key); with --cycle, scopes the cycle lookup instead                            
+  --team        <team>        - Filter by team (key, name, or ID); with --cycle, scopes the cycle lookup instead               
   --cycle       <cycle>       - Filter by cycle: name, number, 'active'/'now', 'next', 'previous', or a relative               
                                 offset like +1 (team from --team or config)                                                    
   --release     <release>     - Filter by release (UUID, name, or version)                                                     
@@ -232,3 +232,17 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Document List Command - Filter By Team ID JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
diff --git a/test/commands/document/__snapshots__/document-update.test.ts.snap b/test/commands/document/__snapshots__/document-update.test.ts.snap
index 78cfbfcb..62f59e6a 100644
--- a/test/commands/document/__snapshots__/document-update.test.ts.snap
+++ b/test/commands/document/__snapshots__/document-update.test.ts.snap
@@ -24,7 +24,8 @@ Options:
   --project           <project>     - Re-point to project (UUID, slug ID, or name); replaces the current attachment     
   --issue             <issue>       - Re-point to issue (identifier like TC-123); replaces the current attachment       
   --initiative        <initiative>  - Re-point to initiative (UUID, slug ID, or name); replaces the current attachment  
-  --team              <team>        - Re-point to team (key); with --cycle, scopes the cycle lookup instead             
+  --team              <team>        - Re-point to team (key, name, or ID); with --cycle, scopes the cycle lookup        
+                                      instead                                                                           
   --cycle             <cycle>       - Re-point to cycle: name, number, 'active'/'now', 'next', 'previous', or a         
                                       relative offset like +1 (team from --team or config)                              
   --release           <release>     - Re-point to release (UUID, name, or version); replaces the current attachment     
diff --git a/test/commands/document/document-create.test.ts b/test/commands/document/document-create.test.ts
index 2520838d..3e3039ad 100644
--- a/test/commands/document/document-create.test.ts
+++ b/test/commands/document/document-create.test.ts
@@ -222,11 +222,17 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const server = new MockLinearServer([
-      // Team keys are uppercased before lookup
+      // The resolver matches keys case-insensitively server-side
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "eng" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "CreateDocument",
@@ -288,9 +294,15 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetTeamCyclesForLookup",
diff --git a/test/commands/document/document-list.test.ts b/test/commands/document/document-list.test.ts
index b93ef1bd..282eb947 100644
--- a/test/commands/document/document-list.test.ts
+++ b/test/commands/document/document-list.test.ts
@@ -235,9 +235,15 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "eng" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "ListDocuments",
@@ -463,3 +469,60 @@ Deno.test("formatDocumentAttachment - labels each target type", () => {
   )
   assertEquals(formatDocumentAttachment({}), "-")
 })
+
+// A team UUID goes through the resolver's id lookup and lands in the same
+// TeamFilter.id filter.
+await snapshotTest({
+  name: "Document List Command - Filter By Team ID JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "11111111-2222-3333-4444-555555555555", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      {
+        queryName: "ResolveTeam",
+        variables: {
+          reference: "11111111-2222-3333-4444-555555555555",
+          id: "11111111-2222-3333-4444-555555555555",
+          isUuid: true,
+        },
+        response: {
+          data: {
+            teams: { nodes: [] },
+            teamById: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "ListDocuments",
+        variables: {
+          filter: { team: { id: { eq: "team-eng-id" } } },
+          first: 50,
+        },
+        response: {
+          data: {
+            documents: {
+              nodes: [],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await listCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/document/document-update.test.ts b/test/commands/document/document-update.test.ts
index a4a0e84e..e5edd055 100644
--- a/test/commands/document/document-update.test.ts
+++ b/test/commands/document/document-update.test.ts
@@ -693,9 +693,15 @@ await snapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "eng" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "UpdateDocument",
diff --git a/test/commands/issue/__snapshots__/issue-create.test.ts.snap b/test/commands/issue/__snapshots__/issue-create.test.ts.snap
index 29e84caa..963d6102 100644
--- a/test/commands/issue/__snapshots__/issue-create.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-create.test.ts.snap
@@ -26,7 +26,7 @@ Options:
   -d, --description          <description>  - Description of the issue                                                      
   --description-file         <path>         - Read description from a file (preferred for markdown content)                 
   -l, --label                <label>        - Issue label associated with the issue. May be repeated.                       
-  --team                     <team>         - Team associated with the issue (if not your default team)                     
+  --team                     <team>         - Team (key, name, or ID) for the issue, if not your default team               
   --project                  <project>      - Project for the issue (UUID, slug ID, or name)                                
   -s, --state                <state>        - Workflow state for the issue (by name or type)                                
   --milestone                <milestone>    - Project milestone (UUID, or name when --project is set)                       
@@ -99,3 +99,22 @@ stderr:
   Valid states: \\"In Progress\\" (started), \\"Todo\\" (unstarted), \\"Done\\" (completed). Run \`linear team states ENG\` to list them.
 "
 `;
+
+snapshot[`Issue Create Command - Unknown Explicit Team Lists Keys 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to create issue: Team not found: Nope
+  Valid team keys: ENG (Engineering). Run \`linear team list\` to see all teams.
+"
+`;
+
+snapshot[`Issue Create Command - Team By Name 1`] = `
+stdout:
+"Creating issue in ENG
+
+https://linear.app/test-team/issue/ENG-1/by-name
+"
+stderr:
+""
+`;
diff --git a/test/commands/issue/__snapshots__/issue-list.test.ts.snap b/test/commands/issue/__snapshots__/issue-list.test.ts.snap
index aa2040b4..25886c70 100644
--- a/test/commands/issue/__snapshots__/issue-list.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-list.test.ts.snap
@@ -11,24 +11,24 @@ Description:
 
 Options:
 
-  -h, --help                       - Show this help.                                                                                                                         
-  -s, --state      <state>         - Filter by issue state (can be repeated for multiple states)                      (Default: [ \\x1b[32m"unstarted"\\x1b[39m ], Values: \\x1b[32m"triage"\\x1b[39m, \\x1b[32m"backlog"\\x1b[39m,
-                                                                                                                      \\x1b[32m"unstarted"\\x1b[39m, \\x1b[32m"started"\\x1b[39m, \\x1b[32m"completed"\\x1b[39m, \\x1b[32m"canceled"\\x1b[39m)       
-  --all-states                     - Show issues from all states                                                                                                             
-  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)                         
-  --team           <team>          - Team to list issues for (if not your default team)                                                                                      
-  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                                              
-  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                                           
-  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                                         
-                                     offset like +1                                                                                                                          
-  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                                                       
-  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                                              
-  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                                          
-  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  -w, --web                        - Open in web browser                                                                                                                     
-  -a, --app                        - Open in Linear.app                                                                                                                      
-  --no-pager                       - Disable automatic paging for long output                                                                                                
+  -h, --help                       - Show this help.                                                                                                
+  -s, --state      <state>         - Filter by workflow state type (triage, backlog, unstarted, started, completed,   (Default: [ \\x1b[32m"unstarted"\\x1b[39m ])    
+                                     canceled), name, or ID (can be repeated for multiple states)                                                   
+  --all-states                     - Show issues from all states                                                                                    
+  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)
+  --team           <team>          - Team key, name, or ID to list issues for (if not your default team)                                            
+  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                     
+  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                  
+  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                
+                                     offset like +1                                                                                                 
+  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                              
+  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                     
+  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                 
+  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  -w, --web                        - Open in web browser                                                                                            
+  -a, --app                        - Open in Linear.app                                                                                             
+  --no-pager                       - Disable automatic paging for long output                                                                       
 
 \`
 stderr:
diff --git a/test/commands/issue/__snapshots__/issue-mine.test.ts.snap b/test/commands/issue/__snapshots__/issue-mine.test.ts.snap
index 688dd4a2..6c855776 100644
--- a/test/commands/issue/__snapshots__/issue-mine.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-mine.test.ts.snap
@@ -11,24 +11,24 @@ Description:
 
 Options:
 
-  -h, --help                       - Show this help.                                                                                                                         
-  -s, --state      <state>         - Filter by issue state (can be repeated for multiple states)                      (Default: [ \\x1b[32m"unstarted"\\x1b[39m ], Values: \\x1b[32m"triage"\\x1b[39m, \\x1b[32m"backlog"\\x1b[39m,
-                                                                                                                      \\x1b[32m"unstarted"\\x1b[39m, \\x1b[32m"started"\\x1b[39m, \\x1b[32m"completed"\\x1b[39m, \\x1b[32m"canceled"\\x1b[39m)       
-  --all-states                     - Show issues from all states                                                                                                             
-  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)                         
-  --team           <team>          - Team to list issues for (if not your default team)                                                                                      
-  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                                              
-  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                                           
-  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                                         
-                                     offset like +1                                                                                                                          
-  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                                                       
-  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                                              
-  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                                          
-  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                                          
-  -w, --web                        - Open in web browser                                                                                                                     
-  -a, --app                        - Open in Linear.app                                                                                                                      
-  --no-pager                       - Disable automatic paging for long output                                                                                                
+  -h, --help                       - Show this help.                                                                                                
+  -s, --state      <state>         - Filter by workflow state type (triage, backlog, unstarted, started, completed,   (Default: [ \\x1b[32m"unstarted"\\x1b[39m ])    
+                                     canceled), name, or ID (can be repeated for multiple states)                                                   
+  --all-states                     - Show issues from all states                                                                                    
+  --sort           <sort>          - Sort order (default: priority, can also be set via LINEAR_ISSUE_SORT)            (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)
+  --team           <team>          - Team key, name, or ID to list issues for (if not your default team)                                            
+  --project        <project>       - Filter by project (UUID, slug ID, or name)                                                                     
+  --project-label  <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                  
+  --cycle          <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                
+                                     offset like +1                                                                                                 
+  --milestone      <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                              
+  -l, --label      <label>         - Filter by label name (can be repeated for multiple labels)                                                     
+  --limit          <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                 
+  --created-after  <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --updated-after  <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  -w, --web                        - Open in web browser                                                                                            
+  -a, --app                        - Open in Linear.app                                                                                             
+  --no-pager                       - Disable automatic paging for long output                                                                       
 
 \`
 stderr:
@@ -50,3 +50,21 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Issue Mine Command - State By Name 1`] = `
+stdout:
+"◌   ID    TITLE     LABELS B E STATE     UPDATED 
+--- ENG-2 Reviewing          - In Review just now
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Mine Command - Unknown State Name 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to list issues: Workflow state not found: 'Done' in team ENG
+  Valid states: \\"Todo\\" (unstarted). State types: triage, backlog, unstarted, started, completed, canceled. Run \`linear team states <team>\` to list a team's states.
+"
+`;
diff --git a/test/commands/issue/__snapshots__/issue-query.test.ts.snap b/test/commands/issue/__snapshots__/issue-query.test.ts.snap
index f0ae3aa5..105d6b2c 100644
--- a/test/commands/issue/__snapshots__/issue-query.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-query.test.ts.snap
@@ -11,30 +11,30 @@ Description:
 
 Options:
 
-  -h, --help                           - Show this help.                                                                                                                       
-  --search             <term>          - Full-text search term                                                                                                                 
-  --search-comments                    - Also search inside issue comments (requires --search)                                                                                 
-  --team               <team>          - Filter by team key (can be repeated for multiple teams)                                                                               
-  --all-teams                          - Query across all teams                                                                                                                
-  -s, --state          <state>         - Filter by issue state (can be repeated for multiple states)                      (Values: \\x1b[32m"triage"\\x1b[39m, \\x1b[32m"backlog"\\x1b[39m, \\x1b[32m"unstarted"\\x1b[39m, \\x1b[32m"started"\\x1b[39m,
-                                                                                                                          \\x1b[32m"completed"\\x1b[39m, \\x1b[32m"canceled"\\x1b[39m)                             
-  --all-states                         - Show issues from all states (this is the default)                                                                                     
-  --assignee           <assignee>      - Filter by assignee (username)                                                                                                         
-  -A, --all-assignees                  - Show issues for all assignees (this is the default)                                                                                   
-  -U, --unassigned                     - Show only unassigned issues                                                                                                           
-  --sort               <sort>          - Sort order: manual or priority (default: priority, not available with --search)  (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)                       
-  --project            <project>       - Filter by project (UUID, slug ID, or name)                                                                                            
-  --project-label      <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                                         
-  --cycle              <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                                       
-                                         offset like +1                                                                                                                        
-  --milestone          <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                                                     
-  -l, --label          <label>         - Filter by label name (can be repeated for multiple labels)                                                                            
-  --limit              <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                                        
-  --created-after      <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                                        
-  --updated-after      <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                                        
-  --include-archived                   - Include archived issues                                                                                                               
-  -j, --json                           - Output results as JSON                                                                                                                
-  --no-pager                           - Disable automatic paging for long output                                                                                              
+  -h, --help                           - Show this help.                                                                                                
+  --search             <term>          - Full-text search term                                                                                          
+  --search-comments                    - Also search inside issue comments (requires --search)                                                          
+  --team               <team>          - Filter by team key, name, or ID (can be repeated for multiple teams)                                           
+  --all-teams                          - Query across all teams                                                                                         
+  -s, --state          <state>         - Filter by workflow state type (triage, backlog, unstarted, started, completed,                                 
+                                         canceled), name, or ID (can be repeated for multiple states)                                                   
+  --all-states                         - Show issues from all states (this is the default)                                                              
+  --assignee           <assignee>      - Filter by assignee (username)                                                                                  
+  -A, --all-assignees                  - Show issues for all assignees (this is the default)                                                            
+  -U, --unassigned                     - Show only unassigned issues                                                                                    
+  --sort               <sort>          - Sort order: manual or priority (default: priority, not available with --search)  (Values: \\x1b[32m"manual"\\x1b[39m, \\x1b[32m"priority"\\x1b[39m)
+  --project            <project>       - Filter by project (UUID, slug ID, or name)                                                                     
+  --project-label      <projectLabel>  - Filter by project label name (shows issues from all projects with this label)                                  
+  --cycle              <cycle>         - Filter by cycle name, number, 'active'/'now', 'next', 'previous', or a relative                                
+                                         offset like +1                                                                                                 
+  --milestone          <milestone>     - Filter by project milestone (UUID, or name when --project is set)                                              
+  -l, --label          <label>         - Filter by label name (can be repeated for multiple labels)                                                     
+  --limit              <limit>         - Maximum number of issues to fetch (default: 50, use 0 for unlimited)             (Default: \\x1b[33m50\\x1b[39m)                 
+  --created-after      <date>          - Filter issues created after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --updated-after      <date>          - Filter issues updated after this date (ISO 8601 or YYYY-MM-DD)                                                 
+  --include-archived                   - Include archived issues                                                                                        
+  -j, --json                           - Output results as JSON                                                                                         
+  --no-pager                           - Disable automatic paging for long output                                                                       
 
 \`
 stderr:
@@ -172,3 +172,268 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Issue Query Command - State By Name JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "issue-1",
+      "identifier": "ENG-101",
+      "title": "Fix login bug",
+      "url": "https://linear.app/test/issue/ENG-101/fix-login-bug",
+      "priority": 2,
+      "priorityLabel": "High",
+      "estimate": 3,
+      "createdAt": "2026-04-01T10:00:00.000Z",
+      "updatedAt": "2026-04-02T08:15:00.000Z",
+      "state": {
+        "id": "state-1",
+        "name": "In Progress",
+        "color": "#f2c94c",
+        "type": "started",
+        "position": 2
+      },
+      "assignee": {
+        "id": "user-1",
+        "name": "jane.smith",
+        "displayName": "Jane Smith",
+        "initials": "JS"
+      },
+      "team": {
+        "id": "team-1",
+        "key": "ENG",
+        "name": "Engineering",
+        "cyclesEnabled": false,
+        "activeCycle": null
+      },
+      "project": {
+        "id": "project-1",
+        "name": "Auth Improvements"
+      },
+      "projectMilestone": null,
+      "cycle": null,
+      "labels": {
+        "nodes": [
+          {
+            "id": "label-1",
+            "name": "Bug",
+            "color": "#eb5757"
+          }
+        ]
+      },
+      "inverseRelations": {
+        "nodes": []
+      }
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
+
+snapshot[`Issue Query Command - Mixed State Types And Names JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "issue-1",
+      "identifier": "ENG-101",
+      "title": "Fix login bug",
+      "url": "https://linear.app/test/issue/ENG-101/fix-login-bug",
+      "priority": 2,
+      "priorityLabel": "High",
+      "estimate": 3,
+      "createdAt": "2026-04-01T10:00:00.000Z",
+      "updatedAt": "2026-04-02T08:15:00.000Z",
+      "state": {
+        "id": "state-1",
+        "name": "In Progress",
+        "color": "#f2c94c",
+        "type": "started",
+        "position": 2
+      },
+      "assignee": {
+        "id": "user-1",
+        "name": "jane.smith",
+        "displayName": "Jane Smith",
+        "initials": "JS"
+      },
+      "team": {
+        "id": "team-1",
+        "key": "ENG",
+        "name": "Engineering",
+        "cyclesEnabled": false,
+        "activeCycle": null
+      },
+      "project": {
+        "id": "project-1",
+        "name": "Auth Improvements"
+      },
+      "projectMilestone": null,
+      "cycle": null,
+      "labels": {
+        "nodes": [
+          {
+            "id": "label-1",
+            "name": "Bug",
+            "color": "#eb5757"
+          }
+        ]
+      },
+      "inverseRelations": {
+        "nodes": []
+      }
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
+
+snapshot[`Issue Query Command - Unknown State Name Lists Valid States 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to query issues: Workflow state not found: 'Done' in team ENG
+  Valid states: \\"Backlog\\" (backlog), \\"In Review\\" (started). State types: triage, backlog, unstarted, started, completed, canceled. Run \`linear team states <team>\` to list a team's states.
+"
+`;
+
+snapshot[`Issue Query Command - All Teams State By Name JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "issue-1",
+      "identifier": "ENG-101",
+      "title": "Fix login bug",
+      "url": "https://linear.app/test/issue/ENG-101/fix-login-bug",
+      "priority": 2,
+      "priorityLabel": "High",
+      "estimate": 3,
+      "createdAt": "2026-04-01T10:00:00.000Z",
+      "updatedAt": "2026-04-02T08:15:00.000Z",
+      "state": {
+        "id": "state-1",
+        "name": "In Progress",
+        "color": "#f2c94c",
+        "type": "started",
+        "position": 2
+      },
+      "assignee": {
+        "id": "user-1",
+        "name": "jane.smith",
+        "displayName": "Jane Smith",
+        "initials": "JS"
+      },
+      "team": {
+        "id": "team-1",
+        "key": "ENG",
+        "name": "Engineering",
+        "cyclesEnabled": false,
+        "activeCycle": null
+      },
+      "project": {
+        "id": "project-1",
+        "name": "Auth Improvements"
+      },
+      "projectMilestone": null,
+      "cycle": null,
+      "labels": {
+        "nodes": [
+          {
+            "id": "label-1",
+            "name": "Bug",
+            "color": "#eb5757"
+          }
+        ]
+      },
+      "inverseRelations": {
+        "nodes": []
+      }
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
+
+snapshot[`Issue Query Command - Team By Name JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "issue-1",
+      "identifier": "ENG-101",
+      "title": "Fix login bug",
+      "url": "https://linear.app/test/issue/ENG-101/fix-login-bug",
+      "priority": 2,
+      "priorityLabel": "High",
+      "estimate": 3,
+      "createdAt": "2026-04-01T10:00:00.000Z",
+      "updatedAt": "2026-04-02T08:15:00.000Z",
+      "state": {
+        "id": "state-1",
+        "name": "In Progress",
+        "color": "#f2c94c",
+        "type": "started",
+        "position": 2
+      },
+      "assignee": {
+        "id": "user-1",
+        "name": "jane.smith",
+        "displayName": "Jane Smith",
+        "initials": "JS"
+      },
+      "team": {
+        "id": "team-1",
+        "key": "ENG",
+        "name": "Engineering",
+        "cyclesEnabled": false,
+        "activeCycle": null
+      },
+      "project": {
+        "id": "project-1",
+        "name": "Auth Improvements"
+      },
+      "projectMilestone": null,
+      "cycle": null,
+      "labels": {
+        "nodes": [
+          {
+            "id": "label-1",
+            "name": "Bug",
+            "color": "#eb5757"
+          }
+        ]
+      },
+      "inverseRelations": {
+        "nodes": []
+      }
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
diff --git a/test/commands/issue/__snapshots__/issue-update.test.ts.snap b/test/commands/issue/__snapshots__/issue-update.test.ts.snap
index 9f809584..325c66ef 100644
--- a/test/commands/issue/__snapshots__/issue-update.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-update.test.ts.snap
@@ -30,7 +30,7 @@ Options:
   --add-label         <label>        - Add a label to the issue, keeping its existing labels. May be repeated.          
   --remove-label      <label>        - Remove a label from the issue, keeping its other labels (does not delete the     
                                        label from the team). May be repeated.                                           
-  --team              <team>         - Team associated with the issue (if not your default team)                        
+  --team              <team>         - Team (key, name, or ID) to move the issue to                                     
   --project           <project>      - Project to assign the issue to (UUID, slug ID, or name)                          
   -s, --state         <state>        - Workflow state for the issue (by name or type)                                   
   --milestone         <milestone>    - Project milestone (UUID, or name when --project is set or the issue already has  
@@ -346,3 +346,14 @@ stderr:
   Run \`linear label list --team ENG\` to see available labels.
 "
 `;
+
+snapshot[`Issue Update Command - Team By Name 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue APP-7: Moved
+https://linear.app/test-team/issue/APP-7/moved
+"
+stderr:
+""
+`;
diff --git a/test/commands/issue/issue-create.test.ts b/test/commands/issue/issue-create.test.ts
index e6ff0a60..e561e473 100644
--- a/test/commands/issue/issue-create.test.ts
+++ b/test/commands/issue/issue-create.test.ts
@@ -5,6 +5,7 @@ import { stub } from "@std/testing/mock"
 import { createCommand } from "../../../src/commands/issue/issue-create.ts"
 import {
   commonDenoArgs,
+  resolveTeamMock,
   setupMockLinearServer,
 } from "../../utils/test-helpers.ts"
 
@@ -43,14 +44,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey() - converting team key to ID
+      // Mock response for resolveTeam() - converting team key to ID
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -116,14 +117,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -206,14 +207,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey() - converting team key to ID
+      // Mock response for resolveTeam() - converting team key to ID
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -282,14 +283,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -367,14 +368,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -468,12 +469,12 @@ Deno.test("Issue Create Command - Explicit Project Still Uses Interactive Mode",
       },
     },
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -590,12 +591,12 @@ Deno.test("Issue Create Command - Interactive Project Prompt Uses Team Projects"
       },
     },
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -726,12 +727,12 @@ Deno.test("Issue Create Command - Additional Fields Can Set Project", async () =
       },
     },
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -860,12 +861,12 @@ Deno.test("Issue Create Command - Additional Fields Can Set Project", async () =
 Deno.test("Issue Create Command - Inherits Parent Project When Project Not Set", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -944,12 +945,12 @@ Deno.test("Issue Create Command - Inherits Parent Project When Project Not Set",
 Deno.test("Issue Create Command - Explicit Project Overrides Parent Project", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1042,12 +1043,12 @@ Deno.test("Issue Create Command - Explicit Project Overrides Parent Project", as
 Deno.test("Issue Create Command - Invalid Parent Project Combination Surfaces Backend Error", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1140,12 +1141,12 @@ Deno.test("Issue Create Command - Invalid Parent Project Combination Surfaces Ba
 Deno.test("Issue Create Command - Config Can Assign Self By Default", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1219,12 +1220,12 @@ Deno.test("Issue Create Command - Auto Assign Mode Respects Linear User Setting
       },
     },
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1328,12 +1329,12 @@ Deno.test("Issue Create Command - Auto Assign Mode Respects Linear User Setting
 Deno.test("Issue Create Command - Explicit Assignee Overrides Config Self Assignment", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1415,12 +1416,12 @@ Deno.test("Issue Create Command - Explicit Assignee Overrides Config Self Assign
 Deno.test("Issue Create Command - Interactive Assignee Can Override Config Self Assignment", async () => {
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1559,9 +1560,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetWorkflowStates",
@@ -1603,3 +1610,84 @@ await snapshotTest({
     }
   },
 })
+
+// An explicit --team that matches nothing errors with the valid keys, even in
+// interactive mode: only the configured default may fall back to a picker.
+await snapshotTest({
+  name: "Issue Create Command - Unknown Explicit Team Lists Keys",
+  meta: import.meta,
+  colors: false,
+  args: ["--title", "Nope", "--team", "Nope", "--no-interactive"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "ResolveTeam",
+        variables: { reference: "Nope" },
+        response: { data: { teams: { nodes: [] } } },
+      },
+      {
+        queryName: "GetAllTeams",
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await createCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// --team by name: the mutation gets the UUID.
+await snapshotTest({
+  name: "Issue Create Command - Team By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--title", "By name", "--team", "Engineering", "--no-interactive"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("Engineering"),
+      {
+        queryName: "CreateIssue",
+        variables: {
+          input: {
+            title: "By name",
+            labelIds: [],
+            teamId: "team-eng-id",
+            useDefaultTemplate: true,
+          },
+        },
+        response: {
+          data: {
+            issueCreate: {
+              success: true,
+              issue: {
+                id: "issue-new-1",
+                identifier: "ENG-1",
+                url: "https://linear.app/test-team/issue/ENG-1/by-name",
+                team: { key: "ENG" },
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG", LINEAR_ISSUE_CREATE_ASSIGN_SELF: "never" })
+
+    try {
+      await createCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
diff --git a/test/commands/issue/issue-list.test.ts b/test/commands/issue/issue-list.test.ts
index 2a2d1e65..6fe69f3b 100644
--- a/test/commands/issue/issue-list.test.ts
+++ b/test/commands/issue/issue-list.test.ts
@@ -40,12 +40,12 @@ Deno.test("Issue List Command - Filter By Label", async () => {
 
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
diff --git a/test/commands/issue/issue-mine.test.ts b/test/commands/issue/issue-mine.test.ts
index c70a9416..ec3ec8f0 100644
--- a/test/commands/issue/issue-mine.test.ts
+++ b/test/commands/issue/issue-mine.test.ts
@@ -6,6 +6,7 @@ import { stub } from "@std/testing/mock"
 import { mineCommand } from "../../../src/commands/issue/issue-mine.ts"
 import {
   commonDenoArgs,
+  resolveTeamMock,
   setupMockLinearServer,
 } from "../../utils/test-helpers.ts"
 
@@ -39,12 +40,12 @@ Deno.test("Issue Mine Command - Filter By Label", async () => {
 
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -144,6 +145,7 @@ Deno.test("Issue Mine Command - Defaults To Priority Sort Without Flag Or Env Va
   // repo's own .linear.toml also sets issue_sort = "priority", so the truly
   // unconfigured default is covered by the subprocess test below.
   const { cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForState",
       variables: {
@@ -212,6 +214,7 @@ Deno.test("Issue Mine Command - Configured Sort Order Wins Over Default", async
   // not override the configured sort. The mock only matches the manual sort
   // payload, so if the default won the request would not match.
   const { cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForState",
       variables: {
@@ -310,6 +313,7 @@ Deno.test("Issue Mine Command - Defaults To Priority Sort When Nothing Is Config
   // HOME and env, so no config file or env var supplies issue_sort. Versions
   // that required sort configuration exit with "Sort must be provided" here.
   const { server, cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForState",
       variables: {
@@ -463,7 +467,7 @@ Deno.test("Issue Mine Command - No Team Error Outside A Repo", async () => {
     assertEquals(
       errorOutput.trim(),
       "✗ Failed to list issues: No default team configured and no team scope provided\n" +
-        "  Use --team <key> to specify a team.",
+        "  Use --team <key, name, or ID> to specify a team.",
     )
   } finally {
     await Deno.remove(tempDir, { recursive: true })
@@ -482,7 +486,7 @@ Deno.test("Issue Mine Command - No Team Error Inside A Repo Suggests linear conf
     assertEquals(
       errorOutput.trim(),
       "✗ Failed to list issues: No default team configured and no team scope provided\n" +
-        "  Use --team <key> to specify a team, or run `linear config` to link this repository to a team.",
+        "  Use --team <key, name, or ID> to specify a team, or run `linear config` to link this repository to a team.",
     )
   } finally {
     await Deno.remove(tempDir, { recursive: true })
@@ -515,9 +519,15 @@ Deno.test("Issue Mine Command - Shows Blocked Indicator", async () => {
 
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "GetIssuesForState",
@@ -680,12 +690,12 @@ Deno.test("Issue Mine Command - Shows Cycle Column", async () => {
 
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
       response: {
         data: {
           teams: {
-            nodes: [{ id: "team-eng-id" }],
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
           },
         },
       },
@@ -1044,3 +1054,132 @@ await cliffySnapshotTest({
     }
   },
 })
+
+// --state accepts a workflow state name, looked up in the configured team.
+// A fixed future update time keeps the relative-time column deterministic.
+await cliffySnapshotTest({
+  name: "Issue Mine Command - State By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--state", "In Review"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetWorkflowStatesInScope",
+        variables: { filter: { team: { key: { in: ["ENG"] } } } },
+        response: {
+          data: {
+            workflowStates: {
+              nodes: [
+                {
+                  id: "s-todo",
+                  name: "Todo",
+                  type: "unstarted",
+                  team: { key: "ENG" },
+                },
+                {
+                  id: "s-rev",
+                  name: "In Review",
+                  type: "started",
+                  team: { key: "ENG" },
+                },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+      {
+        queryName: "GetIssuesForState",
+        variables: {
+          filter: {
+            team: { key: { eq: "ENG" } },
+            state: { id: { in: ["s-rev"] } },
+            assignee: { isMe: { eq: true } },
+          },
+        },
+        response: {
+          data: {
+            issues: {
+              nodes: [
+                {
+                  id: "issue-eng-2",
+                  identifier: "ENG-2",
+                  title: "Reviewing",
+                  priority: 0,
+                  estimate: null,
+                  assignee: { initials: "PS" },
+                  state: {
+                    id: "s-rev",
+                    name: "In Review",
+                    color: "#f2c94c",
+                    type: "started",
+                    position: 1002,
+                  },
+                  labels: { nodes: [] },
+                  cycle: null,
+                  team: {
+                    id: "team-eng-id",
+                    key: "ENG",
+                    cyclesEnabled: false,
+                    activeCycle: null,
+                  },
+                  inverseRelations: { nodes: [] },
+                  updatedAt: "2099-03-29T10:00:00.000Z",
+                },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG", NO_COLOR: "true" })
+
+    try {
+      await mineCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// An unknown state name is an error listing the team's states, not an empty
+// table.
+await cliffySnapshotTest({
+  name: "Issue Mine Command - Unknown State Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--state", "Done"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetWorkflowStatesInScope",
+        variables: { filter: { team: { key: { in: ["ENG"] } } } },
+        response: {
+          data: {
+            workflowStates: {
+              nodes: [
+                {
+                  id: "s-todo",
+                  name: "Todo",
+                  type: "unstarted",
+                  team: { key: "ENG" },
+                },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG", NO_COLOR: "true" })
+
+    try {
+      await mineCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
diff --git a/test/commands/issue/issue-query.test.ts b/test/commands/issue/issue-query.test.ts
index 7ea43a5e..7731d3b5 100644
--- a/test/commands/issue/issue-query.test.ts
+++ b/test/commands/issue/issue-query.test.ts
@@ -9,6 +9,7 @@ import {
 import type { OptionSource } from "../../../src/config.ts"
 import {
   commonDenoArgs,
+  resolveTeamMock,
   setupMockLinearServer,
 } from "../../utils/test-helpers.ts"
 
@@ -91,6 +92,7 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetIssuesForQuery",
         variables: {
@@ -140,6 +142,7 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "SearchIssues",
         variables: {
@@ -261,6 +264,7 @@ Deno.test("Issue Query Command - Shows Blocked Indicator", async () => {
   setColorEnabled(false)
 
   const { cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForQuery",
       response: {
@@ -485,6 +489,7 @@ Deno.test("Issue Query Command - Shows Cycle Column", async () => {
   }
 
   const { cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForQuery",
       response: {
@@ -576,6 +581,7 @@ Deno.test("Issue Query Command - Hides Cycle Column When Cycles Disabled", async
   setColorEnabled(false)
 
   const { cleanup } = await setupMockLinearServer([
+    resolveTeamMock("ENG"),
     {
       queryName: "GetIssuesForQuery",
       response: {
@@ -650,7 +656,7 @@ Deno.test("Issue Query Command - shows note when default team comes from env var
   assertEquals(
     errorLogs.some((l) =>
       l.includes(
-        "Note: using default team ENG. Pass --team <key> or --all-teams to be explicit.",
+        "Note: using default team ENG. Pass --team <key, name, or ID> or --all-teams to be explicit.",
       )
     ),
     true,
@@ -844,3 +850,232 @@ Deno.test("Issue Query Command - Multi-team results group by type without compar
     await cleanup()
   }
 })
+
+// --- --state accepts workflow state names and IDs, resolved within the scope ---
+
+const ENG_STATES_MOCK = {
+  queryName: "GetWorkflowStatesInScope",
+  variables: { filter: { team: { key: { in: ["ENG"] } } } },
+  response: {
+    data: {
+      workflowStates: {
+        nodes: [
+          {
+            id: "s-backlog",
+            name: "Backlog",
+            type: "backlog",
+            team: { key: "ENG" },
+          },
+          {
+            id: "s-review",
+            name: "In Review",
+            type: "started",
+            team: { key: "ENG" },
+          },
+        ],
+        pageInfo: { hasNextPage: false, endCursor: null },
+      },
+    },
+  },
+}
+
+// A state name is looked up in the scoped team and sent as an id filter.
+await snapshotTest({
+  name: "Issue Query Command - State By Name JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "ENG", "--state", "in review", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("ENG"),
+      ENG_STATES_MOCK,
+      {
+        queryName: "GetIssuesForQuery",
+        variables: {
+          filter: {
+            team: { key: { eq: "ENG" } },
+            state: { id: { in: ["s-review"] } },
+          },
+        },
+        response: {
+          data: {
+            issues: {
+              nodes: [mockIssueNode],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { NO_COLOR: "true" })
+
+    try {
+      await queryCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// Mixing a type with a name produces an or-filter; a state ID needs no name
+// match but must exist in the scope.
+await snapshotTest({
+  name: "Issue Query Command - Mixed State Types And Names JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: [
+    "--team",
+    "ENG",
+    "--state",
+    "started",
+    "--state",
+    "In Review",
+    "--json",
+  ],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("ENG"),
+      ENG_STATES_MOCK,
+      {
+        queryName: "GetIssuesForQuery",
+        variables: {
+          filter: {
+            team: { key: { eq: "ENG" } },
+            state: {
+              or: [{ type: { in: ["started"] } }, { id: { in: ["s-review"] } }],
+            },
+          },
+        },
+        response: {
+          data: {
+            issues: {
+              nodes: [mockIssueNode],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { NO_COLOR: "true" })
+
+    try {
+      await queryCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// An unknown state name errors before any issues are fetched and lists what
+// the team actually has.
+await snapshotTest({
+  name: "Issue Query Command - Unknown State Name Lists Valid States",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "ENG", "--state", "Done"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("ENG"),
+      ENG_STATES_MOCK,
+    ], { NO_COLOR: "true" })
+
+    try {
+      await queryCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// With --all-teams a name matches the same-named state in every team, and the
+// state lookup carries no team filter.
+await snapshotTest({
+  name: "Issue Query Command - All Teams State By Name JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: ["--all-teams", "--state", "In Review", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetWorkflowStatesInScope",
+        variables: { filter: undefined },
+        response: {
+          data: {
+            workflowStates: {
+              nodes: [
+                {
+                  id: "s-eng-review",
+                  name: "In Review",
+                  type: "started",
+                  team: { key: "ENG" },
+                },
+                {
+                  id: "s-app-review",
+                  name: "In Review",
+                  type: "started",
+                  team: { key: "APP" },
+                },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+      {
+        queryName: "GetIssuesForQuery",
+        variables: {
+          filter: { state: { id: { in: ["s-eng-review", "s-app-review"] } } },
+        },
+        response: {
+          data: {
+            issues: {
+              nodes: [mockIssueNode],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { NO_COLOR: "true" })
+
+    try {
+      await queryCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// --team accepts a name; the issue filter still uses the canonical key.
+await snapshotTest({
+  name: "Issue Query Command - Team By Name JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "engineering", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("engineering"),
+      {
+        queryName: "GetIssuesForQuery",
+        variables: { filter: { team: { key: { eq: "ENG" } } } },
+        response: {
+          data: {
+            issues: {
+              nodes: [mockIssueNode],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ], { NO_COLOR: "true" })
+
+    try {
+      await queryCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
diff --git a/test/commands/issue/issue-update.test.ts b/test/commands/issue/issue-update.test.ts
index 2f56f64c..861278d5 100644
--- a/test/commands/issue/issue-update.test.ts
+++ b/test/commands/issue/issue-update.test.ts
@@ -2,6 +2,7 @@ import { snapshotTest } from "@cliffy/testing"
 import { updateCommand } from "../../../src/commands/issue/issue-update.ts"
 import {
   commonDenoArgs,
+  resolveTeamMock,
   setupMockLinearServer,
 } from "../../utils/test-helpers.ts"
 
@@ -38,14 +39,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey() - converting team key to ID
+      // Mock response for resolveTeam() - converting team key to ID
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -103,14 +104,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey() - team keys may contain digits
+      // Mock response for resolveTeam() - team keys may contain digits
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "PLA4" },
+        queryName: "ResolveTeam",
+        variables: { reference: "PLA4" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-pla4-id" }],
+              nodes: [{ id: "team-pla4-id", key: "PLA4", name: "Platform" }],
             },
           },
         },
@@ -157,14 +158,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -238,14 +239,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey() - converting team key to ID
+      // Mock response for resolveTeam() - converting team key to ID
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -307,14 +308,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -371,14 +372,14 @@ await snapshotTest({
   denoArgs: commonDenoArgs,
   async fn() {
     const { cleanup } = await setupMockLinearServer([
-      // Mock response for getTeamIdByKey()
+      // Mock response for resolveTeam()
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-id" }],
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -459,9 +460,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "UpdateIssue",
@@ -498,9 +505,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "UpdateIssue",
@@ -540,9 +553,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetWorkflowStates",
@@ -600,9 +619,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       // No GetViewerId mock: --unassign must not perform a user lookup.
       {
@@ -646,9 +671,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "UpdateIssue",
@@ -696,9 +727,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetViewerId",
@@ -766,9 +803,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "UpdateIssue",
@@ -810,9 +853,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetTeamCyclesForLookup",
@@ -899,9 +948,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetTeamCyclesForLookup",
@@ -1003,9 +1058,15 @@ Deno.test("Issue Update Command - relative cycle offset requires an active cycle
   const { stub } = await import("@std/testing/mock")
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "GetTeamCyclesForLookup",
@@ -1068,9 +1129,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetTeamCyclesForLookup",
@@ -1159,9 +1226,15 @@ Deno.test("Issue Update Command - --cycle errors when team has cycles disabled",
   const { stub } = await import("@std/testing/mock")
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "GetTeamCyclesForLookup",
@@ -1210,9 +1283,15 @@ Deno.test("Issue Update Command - --cycle now errors helpfully when no cycle is
   const { stub } = await import("@std/testing/mock")
   const { cleanup } = await setupMockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "GetTeamCyclesForLookup",
@@ -1281,9 +1360,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1339,9 +1424,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1403,9 +1494,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1467,9 +1564,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1539,9 +1642,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1668,9 +1777,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1711,9 +1826,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1740,9 +1861,15 @@ await snapshotTest({
   async fn() {
     const { cleanup } = await setupMockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
-        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
       },
       {
         queryName: "GetIssueLabelIdByNameForTeam",
@@ -1758,3 +1885,64 @@ await snapshotTest({
     }
   },
 })
+
+// --team accepts a name: the mutation gets the UUID and the state lookup uses
+// the canonical key.
+await snapshotTest({
+  name: "Issue Update Command - Team By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--team", "Apps", "--state", "Todo"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      resolveTeamMock("Apps", { id: "team-app-id", key: "APP", name: "Apps" }),
+      {
+        queryName: "GetWorkflowStates",
+        variables: { teamKey: "APP" },
+        response: {
+          data: {
+            team: {
+              states: {
+                nodes: [
+                  {
+                    id: "s-app-todo",
+                    name: "Todo",
+                    type: "unstarted",
+                    position: 1,
+                  },
+                ],
+              },
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: { teamId: "team-app-id", stateId: "s-app-todo" },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "APP-7",
+                url: "https://linear.app/test-team/issue/APP-7/moved",
+                title: "Moved",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
diff --git a/test/commands/label/__snapshots__/label-create.test.ts.snap b/test/commands/label/__snapshots__/label-create.test.ts.snap
new file mode 100644
index 00000000..c61f61ee
--- /dev/null
+++ b/test/commands/label/__snapshots__/label-create.test.ts.snap
@@ -0,0 +1,34 @@
+export const snapshot = {};
+
+snapshot[`Label Create Command - Help Text 1`] = `
+stdout:
+"
+Usage: create
+
+Description:
+
+  Create a new issue label
+
+Options:
+
+  -h, --help                        - Show this help.                                                             
+  -n, --name         <name>         - Label name (required)                                                       
+  -c, --color        <color>        - Color hex code (e.g., #EB5757)                                              
+  -d, --description  <description>  - Label description                                                           
+  -t, --team         <team>         - Team key, name, or ID for a team-specific label (omit for workspace label)  
+  -i, --interactive                 - Interactive mode (default if no flags provided)                             
+
+"
+stderr:
+""
+`;
+
+snapshot[`Label Create Command - Team By Name 1`] = `
+stdout:
+"✓ Created label: backend
+  Color: #5e6ad2
+  Scope: Engineering (ENG)
+"
+stderr:
+""
+`;
diff --git a/test/commands/label/__snapshots__/label-delete.test.ts.snap b/test/commands/label/__snapshots__/label-delete.test.ts.snap
new file mode 100644
index 00000000..8c169f90
--- /dev/null
+++ b/test/commands/label/__snapshots__/label-delete.test.ts.snap
@@ -0,0 +1,29 @@
+export const snapshot = {};
+
+snapshot[`Label Delete Command - Help Text 1`] = `
+stdout:
+"
+Usage: delete <nameOrId>
+
+Description:
+
+  Delete an issue label
+
+Options:
+
+  -h, --help           - Show this help.                                                  
+  -t, --team   <team>  - Team key, name, or ID to disambiguate labels with the same name  
+  -f, --force          - Skip confirmation prompt                                         
+
+"
+stderr:
+""
+`;
+
+snapshot[`Label Delete Command - Team By Name Disambiguates 1`] = `
+stdout:
+"✓ Deleted label: bug (APP)
+"
+stderr:
+""
+`;
diff --git a/test/commands/label/__snapshots__/label-list.test.ts.snap b/test/commands/label/__snapshots__/label-list.test.ts.snap
index 474c3887..a27ea572 100644
--- a/test/commands/label/__snapshots__/label-list.test.ts.snap
+++ b/test/commands/label/__snapshots__/label-list.test.ts.snap
@@ -45,3 +45,28 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Label List Command - Team By Name JSON Output 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "label-2",
+      "name": "backend",
+      "description": "Backend label",
+      "color": "#00ff00",
+      "team": {
+        "key": "ENG",
+        "name": "Engineering"
+      }
+    }
+  ],
+  "pageInfo": {
+    "hasNextPage": false,
+    "endCursor": null
+  }
+}
+'
+stderr:
+""
+`;
diff --git a/test/commands/label/label-create.test.ts b/test/commands/label/label-create.test.ts
new file mode 100644
index 00000000..e86f932f
--- /dev/null
+++ b/test/commands/label/label-create.test.ts
@@ -0,0 +1,61 @@
+import { snapshotTest } from "@cliffy/testing"
+import { createCommand } from "../../../src/commands/label/label-create.ts"
+import { MockLinearServer } from "../../utils/mock_linear_server.ts"
+import { commonDenoArgs, resolveTeamMock } from "../../utils/test-helpers.ts"
+
+await snapshotTest({
+  name: "Label Create Command - Help Text",
+  meta: import.meta,
+  colors: false,
+  args: ["--help"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    await createCommand.parse()
+  },
+})
+
+// --team accepts a name; the mutation receives the team UUID.
+await snapshotTest({
+  name: "Label Create Command - Team By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--name", "backend", "--team", "Engineering"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Engineering"),
+      {
+        queryName: "CreateIssueLabel",
+        variables: {
+          input: { name: "backend", color: "#5E6AD2", teamId: "team-eng-id" },
+        },
+        response: {
+          data: {
+            issueLabelCreate: {
+              success: true,
+              issueLabel: {
+                id: "label-1",
+                name: "backend",
+                color: "#5e6ad2",
+                description: null,
+                team: { key: "ENG", name: "Engineering" },
+              },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await createCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/label/label-delete.test.ts b/test/commands/label/label-delete.test.ts
new file mode 100644
index 00000000..2e439cbb
--- /dev/null
+++ b/test/commands/label/label-delete.test.ts
@@ -0,0 +1,71 @@
+import { snapshotTest } from "@cliffy/testing"
+import { deleteCommand } from "../../../src/commands/label/label-delete.ts"
+import { MockLinearServer } from "../../utils/mock_linear_server.ts"
+import { commonDenoArgs, resolveTeamMock } from "../../utils/test-helpers.ts"
+
+await snapshotTest({
+  name: "Label Delete Command - Help Text",
+  meta: import.meta,
+  colors: false,
+  args: ["--help"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    await deleteCommand.parse()
+  },
+})
+
+// --team by name disambiguates same-named labels on the canonical key: the
+// APP label is deleted, not the ENG one that comes back first.
+await snapshotTest({
+  name: "Label Delete Command - Team By Name Disambiguates",
+  meta: import.meta,
+  colors: false,
+  args: ["bug", "--team", "Apps", "--force"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Apps", { id: "team-app-id", key: "APP", name: "Apps" }),
+      {
+        queryName: "GetLabelByName",
+        variables: { name: "bug" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [
+                {
+                  id: "label-eng-bug",
+                  name: "bug",
+                  color: "#ff0000",
+                  team: { key: "ENG", name: "Engineering" },
+                },
+                {
+                  id: "label-app-bug",
+                  name: "bug",
+                  color: "#ff0000",
+                  team: { key: "APP", name: "Apps" },
+                },
+              ],
+            },
+          },
+        },
+      },
+      {
+        queryName: "DeleteIssueLabel",
+        variables: { id: "label-app-bug" },
+        response: { data: { issueLabelDelete: { success: true } } },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await deleteCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/label/label-list.test.ts b/test/commands/label/label-list.test.ts
index 56038548..997c195a 100644
--- a/test/commands/label/label-list.test.ts
+++ b/test/commands/label/label-list.test.ts
@@ -1,7 +1,7 @@
 import { snapshotTest } from "@cliffy/testing"
 import { listCommand } from "../../../src/commands/label/label-list.ts"
 import { MockLinearServer } from "../../utils/mock_linear_server.ts"
-import { commonDenoArgs } from "../../utils/test-helpers.ts"
+import { commonDenoArgs, resolveTeamMock } from "../../utils/test-helpers.ts"
 
 await snapshotTest({
   name: "Label List Command - JSON Output",
@@ -98,3 +98,55 @@ await snapshotTest({
     }
   },
 })
+
+// --team accepts a name; the label filter is built from the canonical key.
+await snapshotTest({
+  name: "Label List Command - Team By Name JSON Output",
+  meta: import.meta,
+  colors: false,
+  args: ["--team", "Engineering", "--json"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Engineering"),
+      {
+        queryName: "GetIssueLabels",
+        variables: {
+          filter: {
+            or: [{ team: { key: { eq: "ENG" } } }, { team: { null: true } }],
+          },
+          first: 100,
+          after: undefined,
+        },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [
+                {
+                  id: "label-2",
+                  name: "backend",
+                  description: "Backend label",
+                  color: "#00ff00",
+                  team: { key: "ENG", name: "Engineering" },
+                },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await listCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/project/__snapshots__/project-create.test.ts.snap b/test/commands/project/__snapshots__/project-create.test.ts.snap
index f4fc9d2f..9a99deeb 100644
--- a/test/commands/project/__snapshots__/project-create.test.ts.snap
+++ b/test/commands/project/__snapshots__/project-create.test.ts.snap
@@ -23,7 +23,7 @@ Options:
                                            limit)                                                                      
   --content               <markdown>     - Project overview markdown                                                   
   --content-file          <path>         - Read project overview markdown from a file                                  
-  -t, --team              <team>         - Team key (required, can be repeated for multiple teams)                     
+  -t, --team              <team>         - Team key, name, or ID (required, can be repeated for multiple teams)        
   -l, --lead              <lead>         - Project lead (username, email, or @me)                                      
   -s, --status            <status>       - Project status (planned, started, paused, completed, canceled, backlog)     
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                     
@@ -105,3 +105,13 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Project Create Command - Team By Name 1`] = `
+stdout:
+"✓ Created project: API v2
+  Slug: api-v2-abc
+  URL: https://linear.app/test/project/api-v2-abc
+"
+stderr:
+""
+`;
diff --git a/test/commands/project/__snapshots__/project-list.test.ts.snap b/test/commands/project/__snapshots__/project-list.test.ts.snap
index 43ed6901..6a5527b4 100644
--- a/test/commands/project/__snapshots__/project-list.test.ts.snap
+++ b/test/commands/project/__snapshots__/project-list.test.ts.snap
@@ -11,13 +11,13 @@ Description:
 
 Options:
 
-  -h, --help             - Show this help.               
-  --team       <team>    - Filter by team key            
-  --all-teams            - Show projects from all teams  
-  --status     <status>  - Filter by status name         
-  -w, --web              - Open in web browser           
-  -a, --app              - Open in Linear.app            
-  -j, --json             - Output as JSON                
+  -h, --help             - Show this help.                  
+  --team       <team>    - Filter by team key, name, or ID  
+  --all-teams            - Show projects from all teams     
+  --status     <status>  - Filter by status name            
+  -w, --web              - Open in web browser              
+  -a, --app              - Open in Linear.app               
+  -j, --json             - Output as JSON                   
 
 "
 stderr:
@@ -179,3 +179,12 @@ stdout:
 stderr:
 ""
 `;
+
+snapshot[`Project List Command - Web With Unknown Team 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to open projects: Team not found: Nope
+  Valid team keys: ENG (Engineering). Run \`linear team list\` to see all teams.
+"
+`;
diff --git a/test/commands/project/__snapshots__/project-update.test.ts.snap b/test/commands/project/__snapshots__/project-update.test.ts.snap
index bb5d57af..e9daa810 100644
--- a/test/commands/project/__snapshots__/project-update.test.ts.snap
+++ b/test/commands/project/__snapshots__/project-update.test.ts.snap
@@ -27,7 +27,7 @@ Options:
   -l, --lead              <lead>         - Project lead (username, email, or @me)                                      
   --start-date            <startDate>    - Start date (YYYY-MM-DD)                                                     
   --target-date           <targetDate>   - Target date (YYYY-MM-DD)                                                    
-  -t, --team              <team>         - Team key (can be repeated for multiple teams)                               
+  -t, --team              <team>         - Team key, name, or ID (can be repeated for multiple teams)                  
   --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.       
 
 "
diff --git a/test/commands/project/project-create.test.ts b/test/commands/project/project-create.test.ts
index adb47803..8e191a9d 100644
--- a/test/commands/project/project-create.test.ts
+++ b/test/commands/project/project-create.test.ts
@@ -45,12 +45,12 @@ await cliffySnapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-123" }],
+              nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -103,12 +103,12 @@ await cliffySnapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-123" }],
+              nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -185,12 +185,12 @@ await cliffySnapshotTest({
   async fn() {
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-123" }],
+              nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -331,12 +331,12 @@ await cliffySnapshotTest({
 
     const server = new MockLinearServer([
       {
-        queryName: "GetTeamIdByKey",
-        variables: { team: "ENG" },
+        queryName: "ResolveTeam",
+        variables: { reference: "ENG" },
         response: {
           data: {
             teams: {
-              nodes: [{ id: "team-eng-123" }],
+              nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
             },
           },
         },
@@ -457,9 +457,15 @@ Deno.test("Project Create Command - rejects an invalid priority", async () => {
 Deno.test("Project Create Command - rejects an unknown project label", async () => {
   const server = new MockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-123" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "GetProjectLabelIdByName",
@@ -512,9 +518,15 @@ Deno.test("Project Create Command - rejects an unknown project label", async ()
 Deno.test("Project Create Command - rejects an unknown member", async () => {
   const server = new MockLinearServer([
     {
-      queryName: "GetTeamIdByKey",
-      variables: { team: "ENG" },
-      response: { data: { teams: { nodes: [{ id: "team-eng-123" }] } } },
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: {
+        data: {
+          teams: {
+            nodes: [{ id: "team-eng-123", key: "ENG", name: "Engineering" }],
+          },
+        },
+      },
     },
     {
       queryName: "LookupUser",
@@ -563,3 +575,56 @@ Deno.test("Project Create Command - rejects an unknown member", async () => {
     true,
   )
 })
+
+// -t accepts a team name; the mutation receives the UUID.
+await cliffySnapshotTest({
+  name: "Project Create Command - Team By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["--name", "API v2", "-t", "Engineering"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      {
+        queryName: "ResolveTeam",
+        variables: { reference: "Engineering" },
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "CreateProject",
+        variables: { input: { name: "API v2", teamIds: ["team-eng-id"] } },
+        response: {
+          data: {
+            projectCreate: {
+              success: true,
+              project: {
+                id: "project-1",
+                name: "API v2",
+                url: "https://linear.app/test/project/api-v2-abc",
+                slugId: "api-v2-abc",
+              },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await createCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/project/project-list.test.ts b/test/commands/project/project-list.test.ts
index 025fa6c5..2d606927 100644
--- a/test/commands/project/project-list.test.ts
+++ b/test/commands/project/project-list.test.ts
@@ -617,3 +617,50 @@ await cliffySnapshotTest({
     }
   },
 })
+
+// An unknown --team in web mode is a clean error through handleError, not an
+// uncaught stack trace: the resolver runs inside the action's error handling.
+await cliffySnapshotTest({
+  name: "Project List Command - Web With Unknown Team",
+  meta: import.meta,
+  colors: false,
+  args: ["--web", "--team", "Nope"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const server = new MockLinearServer([
+      {
+        queryName: "GetViewer",
+        response: { data: { viewer: { organization: { urlKey: "acme" } } } },
+      },
+      {
+        queryName: "ResolveTeam",
+        variables: { reference: "Nope" },
+        response: { data: { teams: { nodes: [] } } },
+      },
+      {
+        queryName: "GetAllTeams",
+        response: {
+          data: {
+            teams: {
+              nodes: [{ id: "team-eng-id", key: "ENG", name: "Engineering" }],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await listCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/team/__snapshots__/team-delete.test.ts.snap b/test/commands/team/__snapshots__/team-delete.test.ts.snap
new file mode 100644
index 00000000..ce8a22da
--- /dev/null
+++ b/test/commands/team/__snapshots__/team-delete.test.ts.snap
@@ -0,0 +1,38 @@
+export const snapshot = {};
+
+snapshot[`Team Delete Command - Help Text 1`] = `
+stdout:
+"
+Usage: delete <team>
+
+Description:
+
+  Delete a Linear team
+
+Options:
+
+  -h, --help                   - Show this help.                                                     
+  --move-issues  <targetTeam>  - Move all issues to another team (key, name, or ID) before deletion  
+  -y, --force                  - Skip confirmation prompt                                            
+
+"
+stderr:
+""
+`;
+
+snapshot[`Team Delete Command - By Name With Move Target By Name 1`] = `
+stdout:
+"✓ Moved 1 issue(s) to target team
+✓ Successfully deleted team: OLD: Old Team
+"
+stderr:
+""
+`;
+
+snapshot[`Team Delete Command - Move Target Equals Source 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to delete team: Cannot move issues to the same team
+"
+`;
diff --git a/test/commands/team/__snapshots__/team-members.test.ts.snap b/test/commands/team/__snapshots__/team-members.test.ts.snap
index f0ebeadb..5a3b13a5 100644
--- a/test/commands/team/__snapshots__/team-members.test.ts.snap
+++ b/test/commands/team/__snapshots__/team-members.test.ts.snap
@@ -3,11 +3,11 @@ export const snapshot = {};
 snapshot[`Team Members Command - Help Text 1`] = `
 stdout:
 "
-Usage: members [teamKey]
+Usage: members [team]
 
 Description:
 
-  List team members
+  List team members (team by key, name, or ID)
 
 Options:
 
diff --git a/test/commands/team/__snapshots__/team-states.test.ts.snap b/test/commands/team/__snapshots__/team-states.test.ts.snap
index 87d36e73..7fd94b87 100644
--- a/test/commands/team/__snapshots__/team-states.test.ts.snap
+++ b/test/commands/team/__snapshots__/team-states.test.ts.snap
@@ -3,11 +3,11 @@ export const snapshot = {};
 snapshot[`Team States Command - Help Text 1`] = `
 stdout:
 "
-Usage: states [teamKey]
+Usage: states [team]
 
 Description:
 
-  List workflow states for a team
+  List workflow states for a team (by key, name, or ID)
 
 Options:
 
@@ -133,6 +133,74 @@ stdout:
 ""
 stderr:
 "✗ Failed to fetch workflow states: Could not determine team key from directory name
-  Please specify a team key as an argument.
+  Please specify a team key, name, or ID as an argument.
+"
+`;
+
+snapshot[`Team States Command - By Team Name 1`] = `
+stdout:
+'{
+  "nodes": [
+    {
+      "id": "s-triage",
+      "name": "Triage",
+      "type": "triage",
+      "position": 900
+    },
+    {
+      "id": "s-review",
+      "name": "In Review",
+      "type": "started",
+      "position": 1002
+    },
+    {
+      "id": "s-progress",
+      "name": "In Progress",
+      "type": "started",
+      "position": 2
+    },
+    {
+      "id": "s-todo",
+      "name": "Todo",
+      "type": "unstarted",
+      "position": 1
+    },
+    {
+      "id": "s-backlog",
+      "name": "Backlog",
+      "type": "backlog",
+      "position": 0
+    },
+    {
+      "id": "s-done",
+      "name": "Done",
+      "type": "completed",
+      "position": 3
+    },
+    {
+      "id": "s-rejected",
+      "name": "Rejected",
+      "type": "canceled",
+      "position": 0.5
+    },
+    {
+      "id": "s-dupe",
+      "name": "Duplicate",
+      "type": "duplicate",
+      "position": 5
+    }
+  ]
+}
+'
+stderr:
+""
+`;
+
+snapshot[`Team States Command - Unknown Team Lists Keys 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to fetch workflow states: Team not found: Nope
+  Valid team keys: APP (Apps), ENG (Engineering). Run \`linear team list\` to see all teams.
 "
 `;
diff --git a/test/commands/team/team-delete.test.ts b/test/commands/team/team-delete.test.ts
new file mode 100644
index 00000000..e504a747
--- /dev/null
+++ b/test/commands/team/team-delete.test.ts
@@ -0,0 +1,113 @@
+import { snapshotTest } from "@cliffy/testing"
+import { deleteCommand } from "../../../src/commands/team/team-delete.ts"
+import { MockLinearServer } from "../../utils/mock_linear_server.ts"
+import { commonDenoArgs, resolveTeamMock } from "../../utils/test-helpers.ts"
+
+await snapshotTest({
+  name: "Team Delete Command - Help Text",
+  meta: import.meta,
+  colors: false,
+  args: ["--help"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    await deleteCommand.parse()
+  },
+})
+
+const OLD = { id: "team-old-id", key: "OLD", name: "Old Team" }
+const APP = { id: "team-app-id", key: "APP", name: "Apps" }
+
+// Both the team to delete and the --move-issues target resolve by name; the
+// move and the delete mutations get their UUIDs.
+await snapshotTest({
+  name: "Team Delete Command - By Name With Move Target By Name",
+  meta: import.meta,
+  colors: false,
+  args: ["Old Team", "--move-issues", "Apps", "--force"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Old Team", OLD),
+      resolveTeamMock("Apps", APP),
+      {
+        queryName: "GetTeamDetails",
+        variables: { id: "team-old-id" },
+        response: {
+          data: { team: { ...OLD, issues: { nodes: [{ id: "issue-1" }] } } },
+        },
+      },
+      {
+        queryName: "GetTeamIssuesForMove",
+        variables: { teamId: "team-old-id" },
+        response: {
+          data: {
+            team: {
+              issues: {
+                nodes: [{ id: "issue-1", identifier: "OLD-1" }],
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            },
+          },
+        },
+      },
+      {
+        queryName: "MoveIssueToTeam",
+        variables: { id: "issue-1", teamId: "team-app-id" },
+        response: { data: { issueUpdate: { success: true } } },
+      },
+      {
+        queryName: "DeleteTeam",
+        variables: { id: "team-old-id" },
+        response: { data: { teamDelete: { success: true } } },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await deleteCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
+
+// Moving issues into the team being deleted is still rejected when both are
+// given by name.
+await snapshotTest({
+  name: "Team Delete Command - Move Target Equals Source",
+  meta: import.meta,
+  colors: false,
+  args: ["Old Team", "--move-issues", "old", "--force"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Old Team", OLD),
+      resolveTeamMock("old", OLD),
+      {
+        queryName: "GetTeamDetails",
+        variables: { id: "team-old-id" },
+        response: {
+          data: { team: { ...OLD, issues: { nodes: [{ id: "issue-1" }] } } },
+        },
+      },
+    ])
+
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+
+      await deleteCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/commands/team/team-members.test.ts b/test/commands/team/team-members.test.ts
index dd93626b..65a3ebe9 100644
--- a/test/commands/team/team-members.test.ts
+++ b/test/commands/team/team-members.test.ts
@@ -3,6 +3,7 @@ import { assertEquals } from "@std/assert"
 import { membersCommand } from "../../../src/commands/team/team-members.ts"
 import { teamCommand } from "../../../src/commands/team/team.ts"
 import { MockLinearServer } from "../../utils/mock_linear_server.ts"
+import { resolveTeamMock } from "../../utils/test-helpers.ts"
 
 const denoArgs = ["--allow-all", "--quiet"]
 
@@ -81,6 +82,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: false },
@@ -112,6 +114,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: true },
@@ -142,6 +145,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: false },
@@ -169,6 +173,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: true },
@@ -197,6 +202,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: false },
@@ -227,6 +233,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetTeamMembers",
         variables: { teamKey: "ENG", includeDisabled: false, after: undefined },
diff --git a/test/commands/team/team-states.test.ts b/test/commands/team/team-states.test.ts
index ce40ebfc..b0b8aa29 100644
--- a/test/commands/team/team-states.test.ts
+++ b/test/commands/team/team-states.test.ts
@@ -3,6 +3,7 @@ import { assertEquals } from "@std/assert"
 import { statesCommand } from "../../../src/commands/team/team-states.ts"
 import { teamCommand } from "../../../src/commands/team/team.ts"
 import { MockLinearServer } from "../../utils/mock_linear_server.ts"
+import { resolveTeamMock } from "../../utils/test-helpers.ts"
 
 // Common Deno args for permissions
 const denoArgs = ["--allow-all", "--quiet"]
@@ -79,6 +80,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       { queryName: "GetWorkflowStates", response: UNSORTED_STATES },
     ])
     try {
@@ -103,6 +105,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       { queryName: "GetWorkflowStates", response: UNSORTED_STATES },
     ])
     try {
@@ -158,6 +161,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetWorkflowStates",
         response: { data: { team: { states: { nodes: [] } } } },
@@ -185,6 +189,7 @@ await cliffySnapshotTest({
   denoArgs,
   async fn() {
     const server = new MockLinearServer([
+      resolveTeamMock("ENG"),
       {
         queryName: "GetWorkflowStates",
         response: { data: { team: { states: { nodes: [] } } } },
@@ -222,3 +227,75 @@ await cliffySnapshotTest({
     }
   },
 })
+
+// A team name resolves to its key before the states are fetched.
+await cliffySnapshotTest({
+  name: "Team States Command - By Team Name",
+  meta: import.meta,
+  colors: false,
+  args: ["Engineering", "--json"],
+  denoArgs,
+  async fn() {
+    const server = new MockLinearServer([
+      resolveTeamMock("Engineering"),
+      {
+        queryName: "GetWorkflowStates",
+        variables: { teamKey: "ENG" },
+        response: UNSORTED_STATES,
+      },
+    ])
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+      await statesCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
+
+// An unknown team is an error that lists every valid key.
+await cliffySnapshotTest({
+  name: "Team States Command - Unknown Team Lists Keys",
+  meta: import.meta,
+  colors: false,
+  args: ["Nope"],
+  denoArgs,
+  canFail: true,
+  async fn() {
+    const server = new MockLinearServer([
+      {
+        queryName: "ResolveTeam",
+        variables: { reference: "Nope" },
+        response: { data: { teams: { nodes: [] } } },
+      },
+      {
+        queryName: "GetAllTeams",
+        response: {
+          data: {
+            teams: {
+              nodes: [
+                { id: "team-eng-id", key: "ENG", name: "Engineering" },
+                { id: "team-app-id", key: "APP", name: "Apps" },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        },
+      },
+    ])
+    try {
+      await server.start()
+      Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+      Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+      await statesCommand.parse()
+    } finally {
+      await server.stop()
+      Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+      Deno.env.delete("LINEAR_API_KEY")
+    }
+  },
+})
diff --git a/test/utils/linear.test.ts b/test/utils/linear.test.ts
index 83d49da5..8b7f7f83 100644
--- a/test/utils/linear.test.ts
+++ b/test/utils/linear.test.ts
@@ -2,6 +2,7 @@ import { assertEquals, assertRejects, assertStringIncludes } from "@std/assert"
 import { assertThrows } from "@std/assert"
 import {
   compareWorkflowStates,
+  findTeam,
   getIssueIdentifier,
   getStartedState,
   isLinearUuid,
@@ -10,9 +11,13 @@ import {
   resolveMilestoneId,
   resolveProjectId,
   resolveReleaseId,
+  resolveStateSelection,
+  resolveTeam,
+  resolveTeams,
   resolveWorkflowState,
   searchIssuesByTerm,
   type WorkflowState,
+  workflowStateFilter,
   workflowStateNotFoundError,
 } from "../../src/utils/linear.ts"
 import {
@@ -675,3 +680,398 @@ Deno.test("resolveReleaseId - same release matched by name and version is not am
     await cleanup()
   }
 })
+
+// ---------------------------------------------------------------------------
+// Team resolver: key, name, or UUID through one operation
+// ---------------------------------------------------------------------------
+
+const ENG = { id: "team-eng-id", key: "ENG", name: "Engineering" }
+const APP = { id: "team-app-id", key: "APP", name: "Apps" }
+
+const ALL_TEAMS_MOCK = {
+  queryName: "GetAllTeams",
+  response: {
+    data: {
+      teams: {
+        nodes: [ENG, APP],
+        pageInfo: { hasNextPage: false, endCursor: null },
+      },
+    },
+  },
+}
+
+Deno.test("resolveTeam - a key match wins over another team's name", async () => {
+  // "OPS" is both PLT's name and OPS's key. The server returns both under the
+  // or-filter; the key must win regardless of the order they come back in.
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "OPS", isUuid: false },
+      response: {
+        data: {
+          teams: {
+            nodes: [
+              { id: "team-by-name", key: "PLT", name: "OPS" },
+              { id: "team-by-key", key: "OPS", name: "Operations" },
+            ],
+          },
+        },
+      },
+    },
+  ])
+  try {
+    const team = await resolveTeam("OPS")
+    assertEquals(team.id, "team-by-key")
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeam - lowercase key returns the canonical key", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "eng" },
+      response: { data: { teams: { nodes: [ENG] } } },
+    },
+  ])
+  try {
+    assertEquals(await resolveTeam("eng"), ENG)
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeam - a name resolves when no key matches", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "engineering" },
+      response: { data: { teams: { nodes: [ENG] } } },
+    },
+  ])
+  try {
+    assertEquals((await resolveTeam("engineering")).key, "ENG")
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeam - a UUID resolves through the id lookup", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: UUID, id: UUID, isUuid: true },
+      response: {
+        data: { teams: { nodes: [] }, teamById: { nodes: [ENG] } },
+      },
+    },
+  ])
+  try {
+    assertEquals((await resolveTeam(UUID)).key, "ENG")
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeam - two teams with the same name is an error naming their keys", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "Platform" },
+      response: {
+        data: {
+          teams: {
+            nodes: [
+              { id: "t1", key: "PLA", name: "Platform" },
+              { id: "t2", key: "PLT", name: "Platform" },
+            ],
+          },
+        },
+      },
+    },
+  ])
+  try {
+    const error = await assertRejects(
+      () => resolveTeam("Platform"),
+      ValidationError,
+      "ambiguous",
+    )
+    assertStringIncludes(error.message, "PLA (Platform), PLT (Platform)")
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeam - no match lists every valid team key", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "Nope" },
+      response: { data: { teams: { nodes: [] } } },
+    },
+    ALL_TEAMS_MOCK,
+  ])
+  try {
+    const error = await assertRejects(
+      () => resolveTeam("Nope"),
+      NotFoundError,
+      "Team not found: Nope",
+    )
+    assertEquals(
+      error.suggestion,
+      "Valid team keys: APP (Apps), ENG (Engineering). Run `linear team list` to see all teams.",
+    )
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("findTeam - blank reference is rejected before any request", async () => {
+  const { cleanup } = await setupMockLinearServer([])
+  try {
+    await assertRejects(() => findTeam("  "), ValidationError, "empty")
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveTeams - drops references that resolve to the same team", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "ENG" },
+      response: { data: { teams: { nodes: [ENG] } } },
+    },
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "Engineering" },
+      response: { data: { teams: { nodes: [ENG] } } },
+    },
+    {
+      queryName: "ResolveTeam",
+      variables: { reference: "APP" },
+      response: { data: { teams: { nodes: [APP] } } },
+    },
+  ])
+  try {
+    const teams = await resolveTeams(["ENG", "APP", "Engineering"])
+    assertEquals(teams.map((t) => t.key), ["ENG", "APP"])
+  } finally {
+    await cleanup()
+  }
+})
+
+// ---------------------------------------------------------------------------
+// --state selection: type tokens, names, and IDs
+// ---------------------------------------------------------------------------
+
+const SCOPED_STATES = [
+  {
+    id: "s-eng-backlog",
+    name: "Backlog",
+    type: "backlog",
+    team: { key: "ENG" },
+  },
+  {
+    id: "s-eng-review",
+    name: "In Review",
+    type: "started",
+    team: { key: "ENG" },
+  },
+  {
+    id: "s-app-review",
+    name: "In Review",
+    type: "started",
+    team: { key: "APP" },
+  },
+]
+
+function scopedStatesMock(filter: unknown, nodes = SCOPED_STATES) {
+  return {
+    queryName: "GetWorkflowStatesInScope",
+    variables: { filter },
+    response: {
+      data: {
+        workflowStates: {
+          nodes,
+          pageInfo: { hasNextPage: false, endCursor: null },
+        },
+      },
+    },
+  }
+}
+
+Deno.test("workflowStateFilter - keeps the type-only shape and mixes with or", () => {
+  assertEquals(workflowStateFilter({ types: ["started"], stateIds: [] }), {
+    type: { in: ["started"] },
+  })
+  assertEquals(workflowStateFilter({ types: [], stateIds: ["s1"] }), {
+    id: { in: ["s1"] },
+  })
+  assertEquals(
+    workflowStateFilter({ types: ["started"], stateIds: ["s1"] }),
+    { or: [{ type: { in: ["started"] } }, { id: { in: ["s1"] } }] },
+  )
+  assertThrows(
+    () => workflowStateFilter({ types: [], stateIds: [] }),
+    ValidationError,
+  )
+})
+
+Deno.test("resolveStateSelection - bare types need no request", async () => {
+  const { cleanup } = await setupMockLinearServer([])
+  try {
+    const selection = await resolveStateSelection(
+      ["started", "started", "backlog"],
+      { teamKeys: ["ENG"] },
+    )
+    assertEquals(selection, { types: ["started", "backlog"], stateIds: [] })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - a name matches every same-named state in scope", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock({ team: { key: { in: ["ENG", "APP"] } } }),
+  ])
+  try {
+    const selection = await resolveStateSelection(
+      ["completed", "in review"],
+      { teamKeys: ["ENG", "APP"] },
+    )
+    assertEquals(selection, {
+      types: ["completed"],
+      stateIds: ["s-eng-review", "s-app-review"],
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - a capitalized type token is a name lookup", async () => {
+  // Type tokens are the six lowercase words; "Backlog" is the state called
+  // Backlog, not every backlog-type state.
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock({ team: { key: { in: ["ENG"] } } }),
+  ])
+  try {
+    const selection = await resolveStateSelection(["Backlog"], {
+      teamKeys: ["ENG"],
+    })
+    assertEquals(selection, { types: [], stateIds: ["s-eng-backlog"] })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - all teams sends no team filter", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock(undefined),
+  ])
+  try {
+    const selection = await resolveStateSelection(["In Review"], {
+      allTeams: true,
+    })
+    assertEquals(selection.stateIds, ["s-eng-review", "s-app-review"])
+    await assertRejects(
+      () => resolveStateSelection([UUID], { allTeams: true }),
+      NotFoundError,
+      `Workflow state not found: '${UUID}' in any team`,
+    )
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - an unknown name lists the scope's states", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock(
+      { team: { key: { in: ["ENG"] } } },
+      SCOPED_STATES.filter((s) => s.team.key === "ENG"),
+    ),
+  ])
+  try {
+    const error = await assertRejects(
+      () => resolveStateSelection(["Done"], { teamKeys: ["ENG"] }),
+      NotFoundError,
+      "Workflow state not found: 'Done' in team ENG",
+    )
+    assertEquals(
+      error.suggestion,
+      'Valid states: "Backlog" (backlog), "In Review" (started). ' +
+        "State types: triage, backlog, unstarted, started, completed, canceled. " +
+        "Run `linear team states <team>` to list a team's states.",
+    )
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - a state ID outside the scope is not found", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock(
+      { team: { key: { in: ["ENG", "APP"] } } },
+    ),
+  ])
+  try {
+    const error = await assertRejects(
+      () => resolveStateSelection([UUID], { teamKeys: ["ENG", "APP"] }),
+      NotFoundError,
+      "in teams ENG, APP",
+    )
+    // Multi-team scope labels each state with its team.
+    assertStringIncludes(error.suggestion ?? "", '"In Review" (started, APP)')
+    assertStringIncludes(error.suggestion ?? "", '"In Review" (started, ENG)')
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - a state ID matches regardless of case", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    scopedStatesMock({ team: { key: { in: ["ENG"] } } }, [
+      {
+        id: UUID.replace(/0/g, "a"),
+        name: "Todo",
+        type: "unstarted",
+        team: { key: "ENG" },
+      },
+    ]),
+  ])
+  try {
+    const selection = await resolveStateSelection(
+      [UUID.replace(/0/g, "A")],
+      { teamKeys: ["ENG"] },
+    )
+    assertEquals(selection.stateIds, [UUID.replace(/0/g, "a")])
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveStateSelection - a page that never advances is an error, not a hang", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetWorkflowStatesInScope",
+      response: {
+        data: {
+          workflowStates: {
+            nodes: SCOPED_STATES,
+            pageInfo: { hasNextPage: true, endCursor: null },
+          },
+        },
+      },
+    },
+  ])
+  try {
+    await assertRejects(
+      () => resolveStateSelection(["In Review"], { teamKeys: ["ENG"] }),
+      CliError,
+      "no new pagination cursor",
+    )
+  } finally {
+    await cleanup()
+  }
+})
diff --git a/test/utils/test-helpers.ts b/test/utils/test-helpers.ts
index a13b51aa..9e2f3201 100644
--- a/test/utils/test-helpers.ts
+++ b/test/utils/test-helpers.ts
@@ -41,3 +41,21 @@ export async function setupMockLinearServer(
 
   return { server, cleanup }
 }
+
+export const ENG_TEAM = { id: "team-eng-id", key: "ENG", name: "Engineering" }
+
+/**
+ * Mock for the shared team resolver's key/name lookup. The server matches
+ * keys and names case-insensitively, so pass the exact reference the test
+ * sends and the team it should resolve to.
+ */
+export function resolveTeamMock(
+  reference: string,
+  team: { id: string; key: string; name: string } = ENG_TEAM,
+) {
+  return {
+    queryName: "ResolveTeam",
+    variables: { reference },
+    response: { data: { teams: { nodes: [team] } } },
+  }
+}