teleport-acl-lifecycle

Teleport Access List Lifecycle

Use this skill to give users access to specific Teleport resources. Browse available servers, databases, applications, Kubernetes clusters, and more, choose which ones and how users connect to them, then create, update, or retire the access list that grants that access.

Route First

Choose exactly one route before running commands, then read only the files referenced for that route:

User intent	Examples	Do this
Resource listing only	"list AWS IC", "show apps", "what labels do databases have?", "what resources are in the cluster?"	Read RESOURCE_KINDS.md and SECURITY.md. List resources/labels/assignments only; do not draft, create, or update yet.
Create new list	"give alice access to apps", "create Prod SSH access", "bob needs AWS IC"	Read CREATE.md, RESOURCE_KINDS.md, PRESETS.md, SCOPES.md, and SECURITY.md. If create partially succeeds and cleanup/unused-role handling is needed, also read LEFTOVER_ROLES.md.
Update existing list	"add bob to Prod Apps", "add AWS IC to the existing list", "rename the list", "remove app access"	Read UPDATE.md, RESOURCE_KINDS.md, PRESETS.md, LEFTOVER_ROLES.md, SCOPES.md, and SECURITY.md.
Delete existing list	"delete", "remove this list", "retire", "tear down"	Read DELETE.md, PRESETS.md, LEFTOVER_ROLES.md, SCOPES.md, and SECURITY.md.

If the route is unclear, ask whether the user wants to inspect available resources, create a new access list, update an existing access list, or delete an existing access list.

If the user asks to create an access list but gives no access target, such as "create an access list", choose the create route and show CREATE.md's Generic Missing Access Target Prompt.

If the user names people who need access but gives no target, such as "give Alice and Bob access", choose the create route and ask a first-time-friendly resource question. Do not lead with "access list", "grant target", "UUID", or owners. Show CREATE.md's Vague Access Prompt.

If the user names people and a target but does not explicitly ask to create an access list, such as "give app access to claudia", choose the create route and follow CREATE.md's plain-language access bridge.

Critical Gotchas

• Resource listing is not create/update. If the user asks to list, show, or inspect resources, do not draft, create, or update an access list.
• Do not choose resource commands from memory. Use the exact command matrix in RESOURCE_KINDS.md.
• AWS IC is special. Its listing command has no --query flag; use $TCTL integrations awsic accounts ls --format=json and build exact accountID^permissionSetARN assignments from each returned record. AWS IC grants use --aws-ic-assignments, not --app-labels.
• Display title is not the CLI identifier. Existing-list update/delete needs the access-list identifier, and titles are not unique — resolve per SECURITY.md's duplicate-title rule before any acl get, acl update, or acl rm.
• Delete parent detaches are separate writes. A user's permanent-delete confirmation does not approve parent updates discovered later — see DELETE.md's Parent Nesting.
• Access type is immutable. A list created as standing, Access Request (access-request), or custom cannot be converted in place; recreate it. Detect it from the access-list-preset label, not spec.type — see PRESETS.md's Existing Lists section.
• List kind controls legal flags. Access-type lists use resource flags and reject grant flags; custom lists use grant flags and reject resource flags and --remove-access — see UPDATE.md's Legal Changes.
• Update member/owner flags replace sets, not merge. Use tctl acl users add/rm for single member changes instead — see UPDATE.md's Replace Traps.
• Preserve identifier casing exactly. Usernames, logins, principals, role names, and traits are case-sensitive. Pass them into tctl flags exactly as the user typed them, even if surrounding prose capitalizes the name for readability — "give alice access" means the member value is alice, not Alice.
• Never eyeball raw tctl output. It can be huge and may be truncated — capture complete JSON first, then inspect it through filters, per SECURITY.md's Read Capture Discipline.

Use these markers in drafts: (need one), ← default, ← guessed for approval, and (optional, ask).

Presentation

Render structured output with markdown structure, never as one long paragraph. Both tctl JSON and your own drafts must be reshaped into something scannable.

• Resource listings: use a markdown table with one row per resource. Use the route-loaded columns for that resource kind. Do not stream resources inside a sentence. Do not include selector-preview warnings in a listing.

• Selection confirmation: for a previewable label-selected grant, show a markdown table with preview matches and route-loaded warnings. For a user-explicit pattern selector, follow RESOURCE_KINDS.md's no-preview acknowledgement; do not render a table as its match preview.

• Drafts, deltas, and approvals: use a short markdown labeled list or a two-column markdown field | value table. Include applicable fields such as target, type, owners, members, grant target, preview, warnings, removals, and command intent, one field per line. When there is more than one command intent, do not cram them into a single table cell — never use <br> or other HTML to fake a line break inside a cell. List each command on its own line in a fenced bash code block below the table instead.

• Questions and choices: follow the route's stages. Ask only the current stage's missing question(s), then stop for the user's answer. Do not preview or narrate any other unanswered question before the user answers the current one.

  Named reference menus are exact markdown menus owned by their reference files, not structured question tool choices. Render them in full as plain markdown, without truncating, paging, merging, omitting, rewording, or compressing them into a picker. This includes RESOURCE_KINDS.md's Resource Offer List whenever asking for an access target/resource kind, and RESOURCE_KINDS.md's post-listing next-action menu. If you are about to show ☐ Access target, render the Resource Offer List as plain markdown instead.

  Use a structured question tool for small stage-local choices or field batches when available, such as standing vs Access Request, or owners/title/description/members. Use one question per field or choice.

  If no structured question tool is available, use plain markdown with each field or choice on its own line. Never string several asks together in one prose sentence.

  Bad: "Who should own this, what title and description do you want, and who are the members?"

  Good (plain markdown form):

  • Owners (who manages/reviews this list)?
  • Title?
  • Description (optional)?
  • Members (can defer)?

• Put a blank line between sections and use a short bold header or ## when a message has more than one part.

• Keep prose for explanation and warnings only; put data in markdown tables or lists.

Setup

Find tctl (which tctl, /usr/local/bin/tctl, /opt/homebrew/bin/tctl, ~/go/bin/tctl) and set TCTL=<path>. From a workstation, tctl uses the current tsh login; on an auth server it uses local admin identity. If tctl returns access denied, relay the error as data and name the likely permission class: access_list write, plus role access for access-type role work.