# Backlog Full Documentation > Full public documentation corpus for Backlog in one file. Use `/llms.txt` for the curated entry point, `/docs/llms.txt` and `/docs/{interface}/llms.txt` for routing, and `/docs/.../README.md` when you need page-level Markdown. Use this file when you want the entire public docs corpus in one plaintext payload. ## Entry points - [Project root](https://backlog.to/llms.txt): Curated agent entry point for the whole product. - [Docs index](https://backlog.to/docs/llms.txt): Curated directory for the public docs hierarchy. - [Full corpus](https://backlog.to/llms-full.txt): Single plaintext file for bulk ingestion of the public docs corpus. - [Web docs](https://backlog.to/docs/web/llms.txt): Sign in, work in the browser, and run your workspace from the Backlog web app. Covers 13 topics and 42 guides. - [API docs](https://backlog.to/docs/api/llms.txt): Authenticate clients, inspect workspace context, and automate work safely over the Backlog API. Covers 7 topics and 22 guides. - [CLI docs](https://backlog.to/docs/cli/llms.txt): Download the Backlog CLI, authenticate, inspect context, and run terminal-first workflows. Covers 8 topics and 26 guides. - [Docs sitemap](https://backlog.to/docs/sitemap.xml): URL inventory only. Useful for discovery, not as a structured corpus. ## Web Sign in, work in the browser, and run your workspace from the Backlog web app. Source: [Human page](https://backlog.to/docs/web) ### Start Here Choose the right public entry point, finish sign-in, and enter the workspace. #### Get Started Choose the right public page, then move into sign-in or the workspace when you are ready. Source: [Human page](https://backlog.to/docs/web/start) ##### Overview This topic is for readers who are still on the public site and have not entered a workspace yet. Use it to decide whether the next step is docs, product information, pricing, or the first authenticated flow. ##### What you can do - Pick the right public starting point. - Know when to stay on the public site and when to move into sign-in. - Share the right public URL for docs, product, pricing, and legal pages. ##### Open the Right Public Page Choose the right Backlog public page for docs, product, pricing, or sign-in. Source: [Human page](https://backlog.to/docs/web/start/public-site) ###### Overview Backlog has multiple public entry pages, but each one has a different job. This guide helps the reader choose the right first click instead of wandering through unrelated marketing pages. ###### What this page covers - Open the correct public route for the goal. - Know when to stay in the public site and when to move into sign-in or sign-up. - Use docs, pricing, and product pages as stable shareable entry points. ###### Walkthrough Use the public shell to move between Product, Pricing, Docs, Changelog, About, Privacy, and Terms. ###### Touchpoints - Route: /. Primary public landing page. - Route: /product. Product overview. - Route: /pricing. Plan comparison. - Route: /docs. Public manual entry point. ###### Steps 1. Open `/` when the user needs the default public entry point. 2. Choose `/product` if the goal is to explain what Backlog does before any sign-in step. 3. Choose `/pricing` if the goal is plan comparison or commercial review. 4. Choose `/docs` when the goal is task-oriented help instead of marketing copy. 5. Use the shared Sign in or Get started buttons only when the visitor is ready to move into the authenticated product. ###### Notes - Public routes are safe to share broadly because they do not depend on workspace auth state. - Landing-page variants are supporting entry points, not the canonical documentation surface. #### Sign In and Sessions Start sign-in in the browser, finish verification, and keep your human session moving. Source: [Human page](https://backlog.to/docs/web/auth) ##### Overview Backlog uses one human sign-in model across the browser, API, and CLI. Use this topic when the reader needs to start sign-in, finish it, or manage the session after access has been issued. ##### What you can do - Request a sign-in or sign-up code. - Finish verification and land in the right surface. - Refresh or revoke a human session when needed. ##### Request a Sign-In Code Start the OTP flow and send a sign-in code to the correct email address. Source: [Human page](https://backlog.to/docs/web/auth/request-code) ###### What this page covers - Start the OTP flow correctly. - Use the correct purpose value for sign-in or sign-up. - Handle cooldowns and lockouts without guessing. ###### Walkthrough Request the emailed sign-in or sign-up code directly from the browser. ###### Touchpoints - Route: /auth/signin. Use this route for existing users. - Route: /auth/signup. Use this route for new users. ###### Steps 1. Open `/auth/signin` if the person already has access or `/auth/signup` if they are starting fresh. 2. Enter the email address carefully because the code is sent to that exact address. 3. Submit the request and wait for the confirmation state before leaving the page. 4. If the app shows a retry window, wait for that cooldown instead of immediately resubmitting. ###### Notes - The browser flow chooses between `signin` and `signup` based on the page the user started from. ##### Verify the Sign-In Code Complete the OTP flow, establish the human session, and move into the workspace or terminal workflow. Source: [Human page](https://backlog.to/docs/web/auth/verify-code) ###### What this page covers - Submit the code in the correct place. - Capture the returned session tokens when using the API or CLI. - Land in the right post-verification surface. ###### Walkthrough Submit the code from the browser verification handoff and finish onboarding if the flow is a first-run sign-up. ###### Touchpoints - Route: /auth/verify. Browser verification handoff. - Route: /onboarding. First-run path after successful verification. ###### Steps 1. Return to the verification page after reading the emailed code. 2. Enter the six-digit code exactly as received and submit it before the code expires. 3. If the flow is a new-user sign-up, provide any required first-run information and continue into onboarding. 4. Finish onboarding so the session lands inside a usable workspace shell. #### Workspace Context Open the workspace and confirm where you are before you move deeper into the product. Source: [Human page](https://backlog.to/docs/web/workspace) ##### Overview This topic covers the authenticated workspace shell and the commands or endpoints that confirm the active workspace context. Use it when the next step depends on knowing which workspace, principal, or install boundary is active. ##### What you can do - Open the main workspace shell. - Confirm the current principal and workspace. - Check the active workspace before admin or automation work. ##### Open the Workspace Enter the authenticated workspace shell and move into the right surface after sign-in. Source: [Human page](https://backlog.to/docs/web/workspace/open-workspace) ###### What this page covers - Enter the right authenticated route. - Understand the shell quickly. - Move to the next surface without guesswork. ###### Walkthrough Enter the authenticated workspace shell and use it as the base for the rest of the product. ###### Touchpoints - Route: /workspace. Canonical authenticated shell entry. ###### Steps 1. Open `/workspace` after sign-in or onboarding completes. 2. Use the shared shell to move to inbox, search, drafts, tasks, projects, roadmap, teams, members, or settings. 3. Keep the shell open as the base while you drill into deeper entity pages. ###### Notes - The shell stays live even if one feature surface is temporarily unavailable, which lets the user move elsewhere instead of getting trapped. ### Find and Navigate Work Use inbox, search, shortcuts, and drafts to reach the next task quickly. #### Search and Shortcuts Use search or shortcuts to find work faster without scanning the whole workspace. Source: [Human page](https://backlog.to/docs/web/search) ##### Overview Search now lives inside the workspace command palette rather than on a dedicated workspace search page. Use one surface to find records by keyword, scope the search with prefixes, and run contextual actions against the matched result. ##### What you can do - Open the command surface from anywhere in the workspace. - Search records, saved views, and actions from one query. - Understand which commands appear for your current role, memberships, and record context. ##### Search the Workspace Search the workspace command palette across records, saved views, and runnable commands from any page in the shell. Source: [Human page](https://backlog.to/docs/web/search/search-workspace) ###### What this page covers - Search visible workspace records from a single input. - Use prefixes and keywords to narrow the result set. - Understand how ranking, favorites, and contextual actions shape the results. ###### Walkthrough The command palette builds one ranked result set from generic commands, visible records, and contextual actions derived from the best-matching records. ###### Touchpoints - Component: Workspace command palette. Global workspace search and action surface. - Endpoint: GET /api/workspace/command. Loads searchable records and command permissions for the current viewer. ###### Steps 1. Open the palette from any workspace page and start with the plainest terms you know: route name, task title, project key, team key, person name, username, label, or status. 2. Add `@`, `$`, or `#` only when the mixed result list is too broad and you want to force people, projects, or tasks. 3. Review Favorites, Actions, and record groups together. Exact and prefix matches rank highest, then broader keyword and synonym matches, with recent and favorited items boosted. 4. Choose a record to navigate or choose an action to mutate the matched item or open a prefilled create flow. ###### Notes - Search indexes task titles, descriptions, references such as `TEAM-123`, team names and keys, project names and keys, assignee names, labels, statuses, and task comment text. - Projects, people, teams, drafts, and saved views also contribute their names, descriptions, ownership fields, usernames, emails, and scope metadata to the same result set. - Keyword expansion covers synonyms such as task or ticket, project or initiative, assign or owner, complete or done, progress or active, and draft or unpublished. - An empty query shows suggestions instead of a blank state, with Actions and Favorites weighted above the rest of the record set. - Contextual actions are generated only from the highest-ranked matching records, not from every record in the workspace. - Strict scopes still narrow the main result list to the chosen record type. For example, `@aj` returns people matches first, and the selected record can then open its actions menu with `Cmd/Ctrl+K`. - Keyboard navigation always follows the currently rendered filtered result order. Group headings are visual only and do not participate in selection. ###### Scope prefixes - No prefix: All results. Searches commands, favorites, records, and contextual actions together. - `@person`: People. Strict people scope for the main result list. Secondary actions stay available from the selected record actions menu. - `$project`: Projects. Strict project scope for the main result list. Secondary actions stay available from the selected record actions menu. - `#task`: Tasks. Strict task scope for the main result list. Secondary actions stay available from the selected record actions menu. ###### Indexed result sources - Tasks: Title, description, task reference, team, project, assignee, labels, status, comments. Favorite tasks are boosted and grouped under Favorites. - Drafts: Title, description, team, project, assignee, labels, status. Drafts are searchable separately from published tasks. - Projects: Name, key, summary, description, lead, members, labels, related team keys, status, priority. Project favorites are boosted and can also produce contextual actions. - People: Name, username, email, title, bio, workspace role, team keys. People scope is activated by the `@` prefix. - Teams: Name, key, description, expertise area. Team records can produce open and create-task actions. - Views: Name, description, owner, scope type, placement. Includes both task views and project views. - Actions: Generic launchers plus contextual actions from the top matching records. Contextual actions inherit the matched record title and current state. ##### Open the Command Palette Open the command palette from the public site or workspace shell and use it as the fastest launcher. Source: [Human page](https://backlog.to/docs/web/search/open-command-palette) ###### What this page covers - Open the palette from public and workspace routes. - Use keyboard controls to move and execute results quickly. - Understand what happens after navigation, create flows, and mutations. ###### Walkthrough The palette is mounted at both the public layout and the workspace shell, with separate data adapters on top of the same shared primitive. ###### Touchpoints - Shortcut: Cmd/Ctrl+K. Opens the public or workspace palette from the current shell. When focus is already inside the palette, it opens or closes the actions menu for the selected result. - Shortcut: /. Opens the palette on non-editable surfaces. - UI: Public header search. Opens the public command palette on the public site. - UI: Docs search control. Opens the same public palette from docs routes. - UI: Header search control. Opens the palette from the top bar. - UI: Sidebar Search item. Keeps search visible in navigation while still opening the palette. - Route: /workspace/search. Legacy route that now redirects into the palette. - Query param: ?command=1. Shell-level opener that auto-opens and then removes the query param. ###### Steps 1. Use `Cmd/Ctrl+K` to open the palette, press `/` on non-editable surfaces to open it, or click the header or sidebar search control. 2. Start typing. The search field keeps focus while the first result stays selected by default, so `Enter` always runs the active result and `ArrowDown` moves directly to the second item. 3. Press `Cmd/Ctrl+K` again while the palette is focused to open the selected result actions menu. It opens as an anchored popover on desktop and a drawer on smaller screens, exposing more actions such as status changes, assignment, or create flows tied to the record. 4. Use `ArrowUp` and `ArrowDown` to move through either result list, `Enter` to run the active item, `Esc` to close the actions menu when it is open, and `Esc` again to close the palette. 5. If you choose a navigation result, the palette closes and the target route becomes the new working context. 6. If you choose a create action, the palette closes and opens the matching task or project composer with defaults taken from the query or matched record. 7. If you choose a mutation action, the shell posts to `/api/workspace/command`, shows a success toast, invalidates workspace data, and reloads fresh command data on the next open. ###### Notes - The palette lazy-loads command data the first time it opens and prefetches the same payload when the browser is idle. - If loading fails, the palette shows a retry action rather than leaving the shell without search. - The same dialog is shared across inbox, tasks, projects, teams, views, settings, and deeper entity pages because it is mounted in the workspace layout. - The search input owns typing while the active result is exposed through active-descendant state, so you keep typing without losing the current selection. - With an empty query, the opening suggestions are route-aware. The palette suppresses actions that only reopen the current surface, boosts the current record on detail routes, and biases collection routes toward surface-native create commands plus matching records from that route family. - Rows that expose secondary actions show a horizontal ellipsis affordance when they are hovered or active. Clicking it opens the same actions menu as `Cmd/Ctrl+K`. - Type `@`, `$`, and `#` directly in the search field to scope results. `Tab` moves from the search field directly into the selected result row, and from the actions filter directly into the selected action row. - The repeated `Cmd/Ctrl+K` shortcut only switches the actions menu when focus is already inside the palette. Outside the dialog it still behaves as the shell-level launcher. - When the actions menu opens, focus moves into the actions filter so the full secondary action list stays keyboard navigable. - Secondary actions are grouped by intent and ordered for the selected record, with current-status changes and date controls surfaced ahead of lower-frequency actions like favorites or labels. - Public routes use the same command-palette primitive through a public adapter that indexes marketing pages, docs directories, and manual guides through a separate lazy-loaded payload. - The palette announces result counts through a live region for assistive technology. ###### Launcher inventory - Keyboard launcher: `Cmd/Ctrl+K`. Opens or closes the palette from the workspace shell. When focus is already inside the palette it opens or closes the actions menu for the selected result instead of closing the dialog. - Keyboard open: `/`. Opens the dialog when focus is not inside an editable field. - Header search: Workspace top bar. Opens the same global command palette. - Sidebar Search: Workspace navigation. Keeps search visible in the sidebar but does not navigate to a dedicated page. - Legacy search route: `/workspace/search`. Redirects to `/workspace/inbox?command=1`. - Route opener: `?command=1`. Auto-opens the dialog and then removes the query param from the URL. ###### Keyboard controls - Default selection: Open palette or change query. The first result stays selected by default while the search field keeps focus. With an empty query, that first result follows the current route context. - Move main selection: `ArrowUp` and `ArrowDown`. Moves the active result while keeping keyboard control anchored to the search field. Because the first item is already selected, `ArrowDown` moves directly to the second item. Navigation follows the exact filtered result order currently rendered on screen. - Run selected result: `Enter`. Executes the active result when focus is in the search field. - Open actions menu: `Cmd/Ctrl+K`. When focus is inside the open palette, opens the selected result actions menu or closes it if it is already open. - Move action selection: `ArrowUp` and `ArrowDown`. Moves the active action while the action filter keeps focus. - Run selected action: `Enter`. Executes the active action when focus is in the action filter. - Close actions menu: `Esc`. Closes the actions menu and returns focus to the main search input. - Close palette: `Esc`. Closes the dialog when the actions menu is not open. - Selected result row: `Tab`. Moves from the search field directly to the currently selected result row. - Selected action row: `Tab`. Moves from the action filter directly to the currently selected action row. - Result and action buttons: `Enter` or `Space`. Runs the focused row using native button keyboard behavior. ###### Accessibility behavior - Initial focus: Search input. Opening the palette focuses the search field immediately. - Initial active item: First result row. The first available result is active by default even while typing stays in the search field. - Active result state: Listbox with active descendant. The search field exposes the active result to assistive technology. - Actions menu focus: Action filter input. Opening the actions menu moves focus into the action filter and exposes the active action through active-descendant state. - Prefix scopes: Typed directly in search. Type scope prefixes directly in the search field when you want to limit results by people, projects, or tasks. - Result count feedback: Polite live region. The palette announces loading and result counts as the query changes. - Keyboard continuity: Search and actions stay keyboard-first. The same selection model powers the main result list and the secondary actions menu, so the workspace stays navigable without leaving the keyboard. ##### Command Actions and Access Reference Review the full command inventory, who can run each action, and what side effect each action has. Source: [Human page](https://backlog.to/docs/web/search/command-actions-reference) ###### What this page covers - See every command the palette can currently run. - Know which role or record state makes each command appear. - Understand the side effect of running each action. ###### Important boundaries - Scoped queries such as `@person`, `$project`, and `#task` narrow the main results to the matching record type, and the selected record can still open its actions menu. - The main result list favors direct matches and high-priority actions. Secondary entity-specific actions live behind the repeated `Cmd/Ctrl+K` actions menu. - Generic create queries such as `create`, `new`, or `add` intentionally show the primary create ladder first: task, project, team, workflow, task template, project template, and then lower-frequency create actions. - Generic settings queries such as `set`, `sett`, `setting`, or `settings` intentionally show `Open settings` first, then other settings destinations, before unrelated records. - Open and create actions are shown from the current command payload. Mutation actions also depend on server-side write checks at execution time. - The actions menu now includes generated property actions for tasks and projects, including favorites, people assignment, priorities, dates, labels, project moves, and status changes. - Saved-view results now expose owner, scope, favorite, notification, and archive actions where the current viewer is allowed to use them. ###### Walkthrough Command availability is derived from the current workspace command payload, while final write access is enforced again by the underlying task, draft, and project mutations. ###### Touchpoints - Component: Workspace command palette. Shared search and execution surface. - Endpoint: POST /api/workspace/command. Runs supported mutation commands and create-flow launches. ###### Steps 1. Open the palette and match the target command directly or search for the record that should produce contextual actions. 2. Confirm that the action is visible for the current viewer, record state, and scope before you run it. 3. Run the action and let the shell invalidate the affected workspace data so the next surface reflects the mutation. 4. If an expected action is missing, check workspace role, team membership, project-lead status, task-creation availability, and whether the record is visible in the current command payload. ###### Notes - Workspace managers are workspace members whose role is `owner` or `admin`. - Task creation is available to workspace managers and to active team leads or team members while workspace task creation is not commercially blocked. - Task write actions and draft actions still require write access to the matched task team when the command is executed. - Project update actions require the viewer to be a workspace manager or the current lead of the matched project when the command is executed. - Generated secondary actions are derived from live workspace data, so assignment choices, project moves, and label actions only appear for records that are currently available in the command payload. ###### Access rules used by command actions - Workspace manager: Workspace role is `owner` or `admin`. Required for `Create project`, `Create team`, and `Make me lead of project`, and always grants roadmap visibility. - Task creator: Viewer is a workspace manager or an active `lead` or `member` in at least one team, and task creation is not blocked. Required for `Create task`, `Create sub-task`, and create-task actions from project, person, and team results. - Task writer: Viewer is a workspace manager or an active `lead` or `member` on the task team. Required at execution time for task mutation commands such as assignment, priority, deadline, project reassignment, labels, status changes, and draft publish or discard. - Project writer: Viewer is a workspace manager or the current lead of the matched project. Required at execution time for project mutation commands such as lead changes, priority, dates, labels, and status changes. - Roadmap viewer: Viewer is a workspace manager or currently leads at least one project in the workspace. Controls whether `Open roadmap` is available. - Visible record: The record is present in the current `/api/workspace/command` payload. Required before its open action or contextual actions can appear. - Task creation blocked: Workspace usage state blocks new task creation. All task-creation commands disappear even for otherwise eligible users. ###### Global actions - Create task: Task creator. Opens the workspace task composer. Plain-text query text becomes the default task title when present. - Create project: Workspace manager. Opens the workspace project composer. Plain-text query text becomes the default project name when present. - Create team: Workspace manager. Opens the workspace team composer. Plain-text query text becomes the default team name when present. - Invite members: Workspace manager. Opens the member-invite flow from anywhere in the workspace and can default the target team when the current route is a team settings page. - Create workflow: Workspace manager. Navigates into workflow settings and opens the workflow-create dialog immediately. - Create task label: Workspace manager. Navigates into task-label settings and opens the create-label dialog immediately. - Create project label: Workspace manager. Navigates into project-label settings and opens the create-label dialog immediately. - Create task template: Workspace manager. Navigates directly to the new task-template editor route. - Create project template: Workspace manager. Navigates directly to the new project-template editor route. - Create personal API key: Any signed-in workspace member. Navigates into personal API key settings and opens the PAT creation dialog immediately. - Install automation: Workspace manager. Navigates into automation settings and opens the automation-install dialog immediately. - Open inbox: Any signed-in workspace member. Navigates to `/workspace/inbox`. - Open tasks: Any signed-in workspace member. Navigates to `/workspace/tasks`. - Open projects: Any signed-in workspace member. Navigates to `/workspace/projects`. - Open teams: Any signed-in workspace member. Navigates to `/workspace/teams`. - Open members: Workspace manager. Navigates to `/workspace/members`. - Open saved views: Any signed-in workspace member. Navigates to `/workspace/views`. - Open drafts: Any signed-in workspace member. Navigates to `/workspace/drafts`. - Open settings: Any signed-in workspace member. Navigates to `/workspace/settings/preferences`. - Open profile settings: Any signed-in workspace member. Navigates to `/workspace/settings/profile`. - Open preferences: Any signed-in workspace member. Navigates to `/workspace/settings/preferences`. - Open security: Any signed-in workspace member. Navigates to `/workspace/settings/security`. - Open personal API keys: Any signed-in workspace member. Navigates to `/workspace/settings/security/pats`. - Open active sessions: Any signed-in workspace member. Navigates to `/workspace/settings/security/sessions`. - Open team settings: Any signed-in workspace member. Navigates to `/workspace/settings/teams`. - Open workspace settings: Workspace manager. Navigates to `/workspace/settings/workspace`. - Open member settings: Workspace manager. Navigates to `/workspace/settings/members`. - Open workflows: Workspace manager. Navigates to `/workspace/settings/workflows`. - Open task labels: Workspace manager. Navigates to `/workspace/settings/task-labels`. - Open project labels: Workspace manager. Navigates to `/workspace/settings/project-labels`. - Open task templates: Workspace manager. Navigates to `/workspace/settings/task-templates`. - Open project templates: Workspace manager. Navigates to `/workspace/settings/project-templates`. - Open automation: Workspace manager. Navigates to `/workspace/settings/automation`. - Open usage: Workspace manager. Navigates to `/workspace/settings/usage`. - Open billing: Workspace manager. Navigates to `/workspace/settings/billing`. - Open roadmap: Roadmap viewer. Navigates to `/workspace/roadmap`. ###### Task actions - Open task: Matched task is visible. Navigates to the task detail route. - Open project: Matched task has a linked project and is visible. Navigates to the linked project detail route. - Open team: Matched task is visible. Navigates to the linked team profile route. - Open assignee: Matched task has an assignee and is visible. Navigates to the assignee profile route. - Create sub-task: Task creator and matched task is visible. Opens the task composer with the current task as parent and reuses the task team, project, and assignee when available. - Create task in project: Task creator, matched task has a linked project and is visible. Opens the task composer with the linked project preselected. - Create task in team: Task creator and matched task is visible. Opens the task composer with the linked team preselected. - Favorite or unfavorite task: Matched task is visible. Toggles whether the task is pinned inside workspace favorites. - Assign or reassign task to me: Viewer is signed in, matched task is visible, viewer is not already assignee; execution also requires task write access. Updates the task assignee to the current viewer. - Assign task to an eligible teammate: Matched task is visible; execution also requires task write access. Shows one action per eligible team lead or team member and updates the task assignee to the selected person. - Unassign task: Matched task is visible, task currently has an assignee; execution also requires task write access. Clears the current task assignee. - Set task priority: Matched task is visible; execution also requires task write access. Shows one action per allowed priority and updates the stored task priority. - Set, clear, or custom-pick task deadline: Matched task is visible; execution also requires task write access. Shows quick date presets from the task detail surface, can clear the current deadline, and also opens the same custom date picker used on the task detail page. - Move task to another project or remove its project: Matched task is visible; execution also requires task write access. Shows visible workspace projects in a relevance-first order and updates the task project link or clears it. - Add or remove task labels: Matched task is visible; execution also requires task write access. Shows visible task labels with the currently assigned labels first and toggles label membership on the task. - Move task to backlog: Matched task is visible, task status is not `backlogged`; execution also requires task write access. Updates the task status to `backlogged`. - Mark task planned: Matched task is visible, task status is not `planned`; execution also requires task write access. Updates the task status to `planned`. - Mark task in progress: Matched task is visible, status is not `progressed`; execution also requires task write access. Updates the task status to `progressed`. - Complete task: Matched task is visible, status is not `completed`; execution also requires task write access. Updates the task status to `completed`. - Cancel task: Matched task is visible, status is not `cancelled`; execution also requires task write access. Updates the task status to `cancelled`. ###### Draft actions - Open drafts: Matched draft is visible. Navigates to the drafts surface with the matched draft still visible in context. - Publish draft: Matched draft is visible; execution requires task write access on the draft team. Clears draft state, assigns workflow state, records activity, and may send assignment or mention notifications. - Discard draft: Matched draft is visible; execution requires task write access on the draft team. Archives the unpublished draft and removes related asset references. ###### Project actions - Open project: Matched project is visible. Navigates to the project detail route. - Open project lead: Matched project has a current lead and is visible. Navigates to the current lead profile route. - Create task in project: Task creator and matched project is visible. Opens the task composer with the project preselected and a default team chosen from shared related teams when possible. - Favorite or unfavorite project: Matched project is visible. Toggles whether the project is pinned inside workspace favorites. - Make me lead of project: Workspace manager, matched project is visible, viewer is not already lead. Updates the project lead to the current viewer. - Set project lead to a visible person: Matched project is visible; execution requires project write access. Shows visible people in a relevance-first order and updates the project lead. - Set project priority: Matched project is visible; execution requires project write access. Shows one action per allowed priority and updates the stored project priority. - Set, clear, or custom-pick project start date: Matched project is visible; execution requires project write access. Shows the same quick date presets as the project detail surface, can clear the current start date, and also opens the same custom date picker used on the project detail page. - Set, clear, or custom-pick project target date: Matched project is visible; execution requires project write access. Shows the same quick date presets as the project detail surface, can clear the current target date, and also opens the same custom date picker used on the project detail page. - Add or remove project labels: Matched project is visible; execution requires project write access. Shows visible project labels with the currently assigned labels first and toggles label membership on the project. - Move project to backlog: Workspace manager or current project lead, matched project is visible, project status is not `backlog`. Sets the project status override to `backlog`. - Mark project planned: Workspace manager or current project lead, matched project is visible, project status is not `planned`. Sets the project status override to `planned`. - Mark project active: Workspace manager or current project lead, matched project is visible, project status is not `active`. Sets the project status override to `active`. - Complete project: Workspace manager or current project lead, matched project is visible, project status is not `completed`. Sets the project status override to `completed`. - Cancel project: Workspace manager or current project lead, matched project is visible, project status is not `cancelled`. Sets the project status override to `cancelled`. ###### Person actions - Open profile: Matched person is visible. Navigates to the member profile route. - Create task for person: Task creator and matched person is visible. Opens the task composer with the assignee preset and a shared team selected when possible. ###### Team actions - Open team: Matched team is visible. Navigates to the team profile and work surfaces. - Create task in team: Task creator and matched team is visible. Opens the task composer with the team preselected. ###### View actions - Open task view: Matched task view is visible. Navigates to the canonical task-view route. - Open project view: Matched project view is visible. Navigates to the canonical project-view route. - Open saved view: Matched task view or project view is visible and selected in the actions menu. Runs the same canonical view navigation from the secondary actions menu. - Open owner: Matched task view or project view has a visible owner. Navigates to the owner member profile. - Open team: Matched task view or project view is team-scoped and the team is visible. Navigates to the scoped team route. - Open project: Matched task view is project-scoped and the project is visible. Navigates to the scoped project route. - Favorite or unfavorite task view: Matched task view is visible. Pins or unpins the task view inside workspace favorites. - Turn task-view notifications on or off: Matched task view is visible. Subscribes or unsubscribes the current viewer from in-app updates for that task view. - Archive task view: Matched task view is visible and editable. Archives the task view so it no longer appears in active saved-view lists. - Archive project view: Matched project view is visible and editable. Archives the project view so it no longer appears in active saved-view lists. ###### Action-menu behavior - Open second-level actions: Selected result is visible in the palette. Press `Cmd/Ctrl+K` again while focus is already inside the palette. - Filter actions: Actions menu is open. Typing in the actions filter narrows the action list without leaving the keyboard. If no actions match, the menu stays open and shows an empty state. - Run selected command: Selected result is already a command action. The actions menu exposes a single explicit run action so keyboard users can stay within the same secondary action model. ###### Route-aware first result - Task collection route: `/workspace/tasks`. Biases the first result toward `Create task`. - Project collection route: `/workspace/projects`. Biases the first result toward `Create project` when available, then promotes visible project records ahead of unrelated actions. - Team collection route: `/workspace/teams`. Suppresses `Open teams`, biases the first result toward `Create team` when available, and then promotes visible team records plus team-related actions. - Task views collection route: `/workspace/views`. Suppresses `Open saved views`, biases the first result toward `Create task view`, and then promotes visible task views ahead of unrelated actions. - Project views collection route: `/workspace/views/projects`. Suppresses project-view reopen actions, biases the first result toward `Create project view`, and then promotes visible project views. - Members collection route: `/workspace/members`. Suppresses `Open members`, biases the first result toward `Invite members` for workspace managers, and then promotes visible member records. - Settings teams route: `/workspace/settings/teams`. Suppresses settings reopen actions, biases the first result toward `Create team` for workspace managers, and then promotes team-settings entries. - Settings workflows route: `/workspace/settings/workflows`. Biases the first result toward `Create workflow` and then promotes team-settings entries so you can jump into the right team workflow surface. - Settings labels route: `/workspace/settings/task-labels` or `/workspace/settings/project-labels`. Biases the first result toward the matching create-label action and then keeps adjacent settings routes nearby. - Settings templates route: `/workspace/settings/task-templates` or `/workspace/settings/project-templates`. Biases the first result toward the matching create-template action and then keeps the sibling label route nearby. - Settings security route: `/workspace/settings/security` or `/workspace/settings/security/pats`. Biases the first result toward `Create personal API key` and keeps PAT and sessions routes ahead of unrelated actions. - Settings automation route: `/workspace/settings/automation`. Biases the first result toward `Install automation`. - Settings team-detail route: `/workspace/settings/teams/[teamId]`. Promotes invite-member, workflow-creation, create-task, and live-team actions for the current team instead of generic reopeners. - Current record route: Task, project, member, or team detail route. Biases the first result toward the current record so its secondary actions are one shortcut away. - Current saved-view route: Task-view or project-view route. Biases the first result toward the current saved view. - Other collection routes: Inbox, drafts, views, members, settings, roadmap. Suppresses actions that only reopen the current route and instead promotes records and commands that match that route family. #### Notifications and Inbox Review notifications, invitations, and follow-up work from one personal inbox. Source: [Human page](https://backlog.to/docs/web/inbox) ##### Overview Inbox is the personal place for mentions, assignments, and workspace invitations. Use this topic when the reader needs to understand what needs attention and what action to take next. ##### What you can do - Review incoming activity clearly. - Accept or reject invitations. - Jump from a notification back to the related work. ##### Review Notifications Open the inbox, understand what each notification is asking for, and resolve it without losing the work context behind it. Source: [Human page](https://backlog.to/docs/web/inbox/review-notifications) ###### What this page covers - Read personal activity clearly. - Handle invites correctly. - Jump back to the related work item. ###### Walkthrough Use the inbox route as the personal activity center for mentions, assignments, and invites. ###### Touchpoints - Route: /workspace/inbox. Primary inbox route. ###### Steps 1. Open `/workspace/inbox` from the shell or land there automatically after sign-in. 2. Scan the inbox list and open the item that needs attention first. 3. Use the available action control to accept, reject, mark read, mark unread, or archive the item. 4. Open the linked subject when you need to continue from the notification into the task or related surface. ###### Notes - Membership invitations are resolved here, not in a separate public invite center. - Inbox state is personal to the recipient. #### Draft Work Review unfinished work in the browser before it moves into the main task flow. Source: [Human page](https://backlog.to/docs/web/draft) ##### Overview Drafts hold unfinished work that still needs review, cleanup, or a decision. Use this topic when the reader needs to understand what draft tasks are and what to do with them. ##### What you can do - Open the draft surface. - Review unfinished work. - Move from draft review back into active task work. ##### Review Draft Tasks Use the draft surface to inspect unfinished work before it joins the main task flow. Source: [Human page](https://backlog.to/docs/web/draft/review-drafts) ###### What this page covers - Open the draft route. - Understand why the work is still draft work. - Move from drafts into task execution. ###### Walkthrough Drafts are a staging surface for unfinished work that still needs attention. ###### Touchpoints - Route: /workspace/drafts. Draft task review page. ###### Steps 1. Open `/workspace/drafts` from the workspace shell. 2. Read the list of unfinished draft tasks and decide which one should be fixed first. 3. Open the draft or use the available draft actions to move it toward a non-draft state. 4. Return to the main task surfaces once the work is ready to participate in normal execution. ### Tasks and Planning Work through task execution and project planning in the browser. #### Task Workflows Create, review, and update tasks in the browser. Source: [Human page](https://backlog.to/docs/web/task) ##### Overview Tasks are the main execution surface in the product. This topic breaks the work into clear task actions so the reader can go straight to the job they need. ##### What you can do - Pick the right task guide for the job at hand. - Create, inspect, and update tasks step by step. - Choose between browser, API, and CLI paths for the same action. ##### Browse Tasks Open the main task surface, narrow the visible list, and move from the collection view into the next task action. Source: [Human page](https://backlog.to/docs/web/task/browse) ###### What this page covers - Open the main task list. - Filter the collection correctly. - Move from the list into detail or creation. ###### Walkthrough Use the main task page when you want the broadest execution view in the browser. ###### Touchpoints - Route: /workspace/tasks. Primary task list. - Route: /workspace/views. Saved-view entry point. ###### Steps 1. Open `/workspace/tasks` from the shell. 2. Review the current list or board state and any active view selection. 3. Use the page controls to narrow the visible task set before you drill into a single task. 4. Open a task when you need details, or open the composer if the list showed you that new work is missing. ##### Create a Task Create a task with the right title, ownership, and optional planning context from the start. Source: [Human page](https://backlog.to/docs/web/task/create) ###### What this page covers - Use the right creation surface. - Fill required fields first. - Attach optional planning and ownership fields correctly. ###### Walkthrough Create a task in the browser composer with the right title, team, and optional planning fields. ###### Touchpoints - Route: /workspace/tasks. Main entry point for the new-task dialog. - Action: New task button. Header action that opens the composer dialog. ###### Steps 1. Open `/workspace/tasks` and click the new-task action. 2. Enter the title first, then choose the owning team. Those are the minimum creation fields. 3. Add optional fields such as description, assignee, project, milestone, priority, status, deadline, and labels only when they are already known. 4. Submit the dialog and confirm that the task appears in the expected list or view. ###### Notes - The composer can also append reference links directly into the description. ##### Open Task Detail Inspect one task in depth so you can understand status history, ownership, labels, comments, resources, and linked work before changing anything. Source: [Human page](https://backlog.to/docs/web/task/detail) ###### What this page covers - Open the right detail route. - Read the full task context. - Use detail as the base for the next task mutation. ###### Walkthrough Use the detail page whenever list-level information is no longer enough. ###### Touchpoints - Route: /workspace/tasks/[taskId]. Task detail page. ###### Steps 1. Open a task from the task list, inbox, search, or any related project surface. 2. Read the header fields first: title, team, assignee, priority, status, and timing. 3. Review the description, activity history, child tasks, resources, and comments before deciding what to change. 4. Use the property controls only after the context is clear enough to avoid accidental changes. ##### Change Task Status Move a task through its status lifecycle without losing the activity trail that explains what changed and why. Source: [Human page](https://backlog.to/docs/web/task/change-status) ###### What this page covers - Choose a valid status. - Apply the transition from the correct surface. - Preserve a clean activity trail. ###### Walkthrough Use the task detail property control or the relevant list-level action when the only change is status. ###### Touchpoints - Route: /workspace/tasks/[taskId]. Richest status-change surface. - Action: Task status controls. Available in detail and list contexts. ###### Steps 1. Open the task detail page or the task list row that exposes the status control. 2. Choose one of the allowed states: backlogged, planned, progressed, completed, or cancelled. 3. Confirm the UI reflects the new state immediately. 4. Read the activity or timeline if you need to confirm when the transition was recorded. ##### Update Task Details Change ownership, deadlines, labels, project links, description, or other mutable task fields without conflating that work with a status transition. Source: [Human page](https://backlog.to/docs/web/task/update-details) ###### What this page covers - Choose the correct mutation surface. - Use null-clears or clear actions correctly. - Keep the patch focused on the fields that truly changed. ###### Walkthrough Task detail is the richest UI surface for changing fields such as assignee, labels, project, deadline, and description. ###### Touchpoints - Route: /workspace/tasks/[taskId]. Primary detail editing surface. ###### Steps 1. Open the task detail page. 2. Use the property controls to change assignee, labels, project, deadline, or priority one field at a time. 3. Edit the description only when the narrative context itself needs updating. 4. Confirm the new value is visible in the detail page before you move on. ##### Open a Saved Task View Use task saved views when the same filtered slice of work should stay shareable and reusable. Source: [Human page](https://backlog.to/docs/web/task/saved-views) ###### What this page covers - Know where saved views live. - Open the canonical view route. - Use views when a raw list is not enough. ###### Walkthrough Task views are route-backed and should be shared through their canonical detail routes. ###### Touchpoints - Route: /workspace/views. Saved-view hub. - Route: /workspace/view/[viewKey]. Canonical task-view detail route. ###### Steps 1. Open `/workspace/views` when you want to browse saved task views. 2. Choose the saved view that matches the work slice you need. 3. Open the canonical detail route for the selected view. 4. Use the view as the base for daily work when the same filter combination should stay stable and shareable. ###### Notes - Prefer the canonical `/workspace/view/[viewKey]` route over older alias routes when sharing a link. #### Project Planning Browse plans, open project detail, and use the roadmap in the browser. Source: [Human page](https://backlog.to/docs/web/project) ##### Overview Projects are the planning surface for timing, ownership, health, and linked execution work. This topic separates project browsing, project detail, and roadmap reading so the reader can choose the right planning view. ##### What you can do - Browse the project list. - Inspect one project in detail. - Use the roadmap as a planning view. ##### Browse Projects Open the project index, narrow the project collection, and choose the next planning action. Source: [Human page](https://backlog.to/docs/web/project/browse) ###### What this page covers - Open the project index. - Filter by status or ownership. - Move from the index into project detail. ###### Walkthrough Use the browser project index when you want the full planning collection with saved views and creation tools. ###### Touchpoints - Route: /workspace/projects. Primary project index. - Route: /workspace/views/projects. Project-view collection page. ###### Steps 1. Open `/workspace/projects` from the shell. 2. Switch between All and Owned when you want to narrow by responsibility first. 3. Use the active-only control or a saved project view when the collection still feels too broad. 4. Open the target project row or card once you know which project needs deeper review. ##### Open Project Detail Inspect a single project deeply so you can understand health, ownership, milestones, timing, and linked execution work. Source: [Human page](https://backlog.to/docs/web/project/detail) ###### What this page covers - Open a specific project. - Read planning context before editing. - Use project detail as the base for roadmap or task work. ###### Walkthrough Project detail is the planning counterpart to task detail, milestones, and roadmap context. ###### Touchpoints - Route: /workspace/projects/[projectId]. Project detail page. ###### Steps 1. Open the target project from the index, team project slice, or roadmap. 2. Read the project summary, lead, timing, status, and health indicators first. 3. Inspect milestones, linked tasks, dependencies, or updates before changing any planning fields. 4. Use the available inline controls only after the project context is clear enough for a safe change. ##### Use the Roadmap Read the roadmap when you need a timeline-oriented planning view instead of a single-project deep dive. Source: [Human page](https://backlog.to/docs/web/project/roadmap) ###### What this page covers - Choose roadmap for time-oriented planning. - Move from roadmap into project detail. - Use roadmap as a planning lens, not a replacement for project detail. ###### Walkthrough Roadmap helps the reader compare multiple projects against time and planning state. ###### Touchpoints - Route: /workspace/roadmap. Workspace roadmap route. ###### Steps 1. Open `/workspace/roadmap` from the shell or from the task header shortcut. 2. Read the visible planning timeline and timing indicators to understand what is moving, slipping, or blocked. 3. Open the project that needs closer inspection. 4. Return to roadmap after the project detail review when you need to continue across multiple projects. ### People and Teams Open profiles, understand team ownership, and move into team-scoped work. #### People and Profiles Find people and open profiles before you switch into admin settings. Source: [Human page](https://backlog.to/docs/web/member) ##### Overview Member pages are for understanding people, not for changing workspace access. Use this topic when the reader needs profile context first and only later decides whether admin changes are required. ##### What you can do - Browse the people directory. - Open a profile. - Know when to switch from profile reading to access administration. ##### Browse the Member Directory Open the workspace member list and find the person you need before you switch into profile or settings work. Source: [Human page](https://backlog.to/docs/web/member/browse) ###### What this page covers - Open the directory. - Find the right person. - Know when to switch from reading to administration. ###### Walkthrough The member directory is the read-oriented people index for finding profiles and context. ###### Touchpoints - Route: /workspace/members. Member directory route. ###### Steps 1. Open `/workspace/members` from the shell. 2. Scan the directory to find the person you want to inspect. 3. Open the profile when you need the individual detail page. 4. Switch to settings if the actual goal is to change access rather than just read member information. ##### Open a Member Profile Inspect one member profile to understand their workspace identity, team presence, and visible context. Source: [Human page](https://backlog.to/docs/web/member/profile) ###### What this page covers - Open the correct profile. - Read the member context clearly. - Know when to move into admin settings. ###### Walkthrough Member profiles are for understanding a person, not changing their admin state. ###### Touchpoints - Route: /workspace/members/[profileId]. Member profile route. ###### Steps 1. Open the profile from the member directory or another people surface. 2. Read the visible profile information, team context, and related workspace presence. 3. Use this page to understand who the person is in the workspace. 4. Switch to settings if the next step is invitation, role, or team membership administration. #### Teams and Ownership Browse teams, open team detail, and stay inside team-scoped work. Source: [Human page](https://backlog.to/docs/web/team) ##### Overview Teams shape ownership, task access, and planning slices across the workspace. This topic covers the team catalog, team detail, and the places where team-scoped work begins. ##### What you can do - Open the team catalog. - Inspect one team. - Use team-scoped pages to narrow the work view. ##### Browse Teams Open the team catalog and choose the team that matters before you move into team detail or team-scoped work. Source: [Human page](https://backlog.to/docs/web/team/browse) ###### What this page covers - Open the team catalog. - Choose a team safely. - Know when to move into team detail. ###### Walkthrough The team catalog is the broadest team surface in the main workspace shell. ###### Touchpoints - Route: /workspace/teams. Team catalog route. ###### Steps 1. Open `/workspace/teams` from the shell. 2. Review the visible team set and choose the team you actually need. 3. Open the team detail page for deeper context. 4. Switch into team projects or team views after the team itself is clear. ##### Open Team Detail Inspect one team and use that page as the base for team-scoped projects, views, and profile work. Source: [Human page](https://backlog.to/docs/web/team/detail) ###### What this page covers - Read the team context first. - Open the correct team-scoped child route. - Use the team page to understand ownership and membership. ###### Walkthrough Team detail is the hub for one team’s ownership and delivery context. ###### Touchpoints - Route: /workspace/teams/[teamId]. Team detail route. - Route: /workspace/teams/[teamId]/projects. Team projects slice. - Route: /workspace/teams/[teamId]/views. Team saved-view slice. ###### Steps 1. Open the target team from the team catalog. 2. Read the team detail page to understand who owns the team and what work it contains. 3. Choose the team projects route when the next step is planning work, or choose the team views route when the next step is a filtered slice. 4. Use the team route family instead of the full workspace when the goal is clearly team-scoped. ### Settings, Access, and Automation Run personal settings, workspace configuration, security, and automation management. #### Settings and Configuration Go straight to the settings page that matches the change you need to make. Source: [Human page](https://backlog.to/docs/web/settings) ##### Overview Settings work is split by area so personal changes and shared configuration do not blur together. Use this topic when the reader knows something needs to change and wants the shortest path to the right settings page. ##### What you can do - Open the right settings route first. - Follow route-specific steps instead of a generic settings article. - Separate personal configuration from workspace administration. ##### Update Your Profile Settings Use the profile settings page for personal account-level changes that belong to you rather than the whole workspace. Source: [Human page](https://backlog.to/docs/web/settings/profile) ###### What this page covers - Open the personal settings page. - Change the correct kind of personal data. - Keep workspace administration separate from profile edits. ###### Walkthrough Update personal account details from the profile settings page without changing workspace-wide configuration. ###### Touchpoints - Route: /workspace/settings/profile. Personal profile settings. ###### Steps 1. Open `/workspace/settings/profile` from the settings shell. 2. Review the current profile fields and update only the values that belong to your own identity. 3. Save the changes and confirm the profile page reflects the new state. 4. Move to another settings route only if the next change belongs to the workspace rather than to you personally. ##### Update Your Preferences Use preferences for appearance or personal UX settings that change how the product feels, not what the workspace stores globally. Source: [Human page](https://backlog.to/docs/web/settings/preferences) ###### What this page covers - Open the right route for personal UX choices. - Keep preference changes separate from workspace configuration. ###### Walkthrough Preferences are personal UI choices rather than shared product configuration. ###### Touchpoints - Route: /workspace/settings/preferences. Preferences route. ###### Steps 1. Open `/workspace/settings/preferences` from the settings shell. 2. Review the available preference controls such as presentation or appearance choices. 3. Change the value you need and confirm the new preference is active. 4. Return to the main product when the preference change is complete. ##### Update Workspace Settings Use the workspace settings page for workspace-wide metadata and identity changes. Source: [Human page](https://backlog.to/docs/web/settings/workspace) ###### What this page covers - Open the workspace-wide settings route. - Change workspace-level identity safely. - Keep people administration on its own route. ###### Walkthrough Workspace settings are for the workspace itself, not individual members or teams. ###### Touchpoints - Route: /workspace/settings/workspace. Workspace settings route. ###### Steps 1. Open `/workspace/settings/workspace`. 2. Review the current workspace-level fields before changing any of them. 3. Update the workspace identity or metadata fields that truly apply to the whole workspace. 4. Save the changes and verify the shell and related workspace surfaces reflect the new state. ##### Manage Workspace Members Use the member administration route for invitations and access changes rather than the read-only member directory. Source: [Human page](https://backlog.to/docs/web/settings/members) ###### What this page covers - Open the administrative member route. - Invite or manage people in the right surface. - Separate viewing people from changing access. ###### Walkthrough Use the member administration settings route for invitations, roles, and workspace access changes. ###### Touchpoints - Route: /workspace/settings/members. Administrative member settings route. ###### Steps 1. Open `/workspace/settings/members` from the settings shell. 2. Review the current member set and choose whether the next action is invitation, role adjustment, or access review. 3. Use the member administration controls to complete the change. 4. Return to the member directory only when the goal switches back to read-only people browsing. ##### Manage Teams from Settings Use the team administration routes when the goal is to create or maintain team structure rather than simply browse teams. Source: [Human page](https://backlog.to/docs/web/settings/teams) ###### What this page covers - Open the right team administration route. - Manage team structure safely. - Keep team browsing and team administration separate. ###### Walkthrough Team settings are the administrative counterpart to the main team pages. ###### Touchpoints - Route: /workspace/settings/teams. Team settings index. - Route: /workspace/settings/teams/[teamId]. Single-team admin page. - Route: /workspace/settings/teams/[teamId]/members. Canonical team-members admin route. ###### Steps 1. Open `/workspace/settings/teams` when you need to create or manage team structure. 2. Choose the target team if the change applies to an existing team. 3. Open the team-members route when the real change is who belongs to the team. 4. Save the change and then verify the visible team surfaces reflect the new structure. ###### Notes - Ignore the legacy typo alias route when sharing links; the canonical team-members route is the stable one. ##### Manage Task Labels Use the task label settings route when the shared task vocabulary itself needs to change. Source: [Human page](https://backlog.to/docs/web/settings/task-labels) ###### What this page covers - Open the label route. - Edit shared task labels in one place. - Return to task work with the updated vocabulary. ###### Walkthrough Task labels are shared task metadata, so their administration belongs in settings. ###### Touchpoints - Route: /workspace/settings/task-labels. Task label settings route. ###### Steps 1. Open `/workspace/settings/task-labels`. 2. Review the current task label set. 3. Add, rename, or otherwise maintain the shared label vocabulary through the available controls. 4. Return to tasks once the shared label set is in the state you want. ##### Manage Project Labels Use the project label settings route when the shared project label catalog needs a workspace-wide change. Source: [Human page](https://backlog.to/docs/web/settings/project-labels) ###### What this page covers - Open the project label route when shared labels need to change. - Create, edit, or archive shared project labels. - Assign project labels from project detail or creation. ###### Walkthrough Project labels describe planning-level categorization. Manage the shared catalog in settings, then assign labels from project detail or project creation. ###### Touchpoints - Route: /workspace/settings/project-labels. Project label settings route. ###### Steps 1. Open `/workspace/settings/project-labels` when the shared catalog itself needs to change. 2. Review the shared labels used across projects. 3. Create, edit, or archive labels through the page controls. 4. Return to project detail or project creation to assign the labels where needed. ##### Manage Task Templates Use the task template routes when a repeatable task shape should be captured as reusable configuration. Source: [Human page](https://backlog.to/docs/web/settings/task-templates) ###### What this page covers - Open the template index. - Start a new template. - Return to task creation with reusable defaults. ###### Walkthrough Task templates are reusable configuration assets, not one-off tasks for a single workflow. ###### Touchpoints - Route: /workspace/settings/task-templates. Task template index. - Route: /workspace/settings/task-templates/new. New task template route. - Route: /workspace/settings/task-templates/[templateId]. Task template editor. ###### Steps 1. Open the task template index to review what already exists. 2. Use the new-template route when the desired template does not exist yet. 3. Open the template detail route when the template already exists and needs maintenance. 4. Return to task creation flows once the template is ready for use. ##### Manage Project Templates Use the project template routes when a repeatable project structure should become reusable configuration. Source: [Human page](https://backlog.to/docs/web/settings/project-templates) ###### What this page covers - Open the project template index. - Create or edit a reusable project template. - Apply the template back in project creation. ###### Walkthrough Project templates do for projects what task templates do for tasks. ###### Touchpoints - Route: /workspace/settings/project-templates. Project template index. - Route: /workspace/settings/project-templates/new. New project template route. - Route: /workspace/settings/project-templates/[templateId]. Project template editor. ###### Steps 1. Open the project template index to see whether the needed template already exists. 2. Use the new-template route for a brand-new template. 3. Use the detail route for an existing template that needs maintenance. 4. Return to project creation once the reusable template is ready to apply. #### Sessions and Personal Tokens Review sessions and manage personal tokens without mixing them with shared automation credentials. Source: [Human page](https://backlog.to/docs/web/security) ##### Overview Security work is easier to follow when sessions and personal tokens are treated as separate jobs. This topic focuses on human-scoped credentials and session review, not workspace-shared automations. ##### What you can do - Review session state. - List personal tokens. - Create or revoke a personal token. ##### Review Security Sessions Use the sessions page to understand the current browser security context and active session state. Source: [Human page](https://backlog.to/docs/web/security/review-sessions) ###### What this page covers - Open the session review page. - Understand current session state. - Move to PAT work only when the goal is API key management. ###### Walkthrough The sessions page is for browser or session review, not for shared automation credentials. ###### Touchpoints - Route: /workspace/settings/security/sessions. Security sessions route. ###### Steps 1. Open `/workspace/settings/security/sessions` from the security settings shell. 2. Review the visible session information and current authentication context. 3. Decide whether the next step is session review only or whether you actually need a personal API key instead. 4. Switch to the PAT guides only if the user now needs a CLI or script credential. ##### List Personal Access Tokens Review the current personal API keys before creating a new one or revoking an old one. Source: [Human page](https://backlog.to/docs/web/security/list-personal-access-tokens) ###### What this page covers - Open the correct PAT list surface. - Read current token status safely. - Use the list before create or revoke actions. ###### Walkthrough The browser PAT page is the clearest place to review label, scope, expiry, and status for existing keys. ###### Touchpoints - Route: /workspace/settings/security/pats. Personal API key management route. ###### Steps 1. Open `/workspace/settings/security/pats`. 2. Review the visible token list and read the status chips for each key. 3. Use the list to decide whether you truly need a new key or whether an old key should be revoked. 4. Move into the create or revoke guide only after the existing key set is clear. ##### Create a Personal Access Token Create a human-owned API key with the narrowest useful scope set and store it safely because the raw token is only shown once. Source: [Human page](https://backlog.to/docs/web/security/create-personal-access-token) ###### What this page covers - Choose scopes deliberately. - Copy the raw token immediately. - Use PATs only for human-owned automation. ###### Important boundaries - PATs belong to a human and never exceed the human role. They are not workspace-shared automation credentials. ###### Walkthrough The browser PAT page explains scope meaning clearly before the key is issued. ###### Touchpoints - Route: /workspace/settings/security/pats. PAT management page. ###### Steps 1. Open the PAT page and start the create flow. 2. Choose a label, expiry, and only the scopes the workflow truly needs. 3. Create the key and copy the raw token immediately because the page only shows it once. 4. Store the token in the tool that will use it and never expect the browser to reveal it again later. ##### Revoke a Personal Access Token Revoke a human-owned API key by credential id when it is obsolete, leaked, or no longer appropriate for the workflow. Source: [Human page](https://backlog.to/docs/web/security/revoke-personal-access-token) ###### What this page covers - Find the right credential id first. - Use the correct revoke surface. - Confirm the key should no longer be used anywhere. ###### Walkthrough The browser PAT page exposes the existing key list and its revoke actions together. ###### Touchpoints - Route: /workspace/settings/security/pats. PAT management page. ###### Steps 1. Open the PAT page and locate the credential entry you want to remove. 2. Double-check the label, prefix, and status so you do not revoke the wrong key. 3. Use the revoke action on that entry. 4. Remove the raw token from any downstream system that was still using it. #### Automation and Agents Create automations, rotate secrets, and manage visible agents from workspace settings. Source: [Human page](https://backlog.to/docs/web/automation) ##### Overview Workspace automations and visible agents are related, but they are not the same thing. This topic separates installation work from agent work so the reader can change the right object at the right time. ##### What you can do - Create and maintain workspace automations safely. - Exchange automation secrets correctly. - Create and update visible agents under an automation. ##### List Automations Review the current workspace automations before you create, update, or rotate one. Source: [Human page](https://backlog.to/docs/web/automation/list-automations) ###### What this page covers - Open the current automation inventory. - Choose the right automation id. - Avoid editing the wrong automation. ###### Walkthrough The browser automation settings page is the most contextual inventory view for workspace automations. ###### Touchpoints - Route: /workspace/settings/automation. Workspace automation settings route. ###### Steps 1. Open `/workspace/settings/automation`. 2. Review the automation list before making any changes. 3. Identify the automation id, name, scope, and current secret state that matter for the next action. 4. Move into create, update, rotate, or agent work only after the right automation is identified. ##### Create an Automation Create the workspace automation boundary, issue the automation secret, and store that secret safely because it is only shown once. Source: [Human page](https://backlog.to/docs/web/automation/create-automation) ###### What this page covers - Create the automation boundary correctly. - Choose scopes and team limits deliberately. - Capture the secret safely the first time. ###### Walkthrough The browser automation settings page presents automation creation in a focused dialog. ###### Touchpoints - Route: /workspace/settings/automation. Workspace automation settings page. ###### Steps 1. Open `/workspace/settings/automation` and start the automation creation flow. 2. Enter the automation name and description, then set provider type, team scope, capabilities, and the optional secret label. 3. Create the automation and copy the issued automation secret immediately. 4. Store the secret in the automation host or secrets manager that will actually use it. ###### Notes - Treat the automation secret like a production credential. The page does not show the raw token again later. ##### Update an Automation Change automation metadata, team boundaries, scopes, or suspension state without recreating the automation. Source: [Human page](https://backlog.to/docs/web/automation/update-automation) ###### What this page covers - Edit the correct automation. - Narrow scopes safely. - Suspend access without deleting context. ###### Walkthrough The browser automation settings page is the most contextual place to maintain automation settings over time. ###### Touchpoints - Route: /workspace/settings/automation. Automation maintenance surface. ###### Steps 1. Open the automation settings page and locate the automation you want to maintain. 2. Change only the fields that truly need updating: description, team scope, scope set, or suspension state. 3. Save the update and confirm the automation entry reflects the new state. 4. If the next action is secret rotation instead of metadata maintenance, switch to the rotate-secret guide instead. ##### Rotate an Automation Secret Issue a new automation secret when the old one should no longer be trusted, then replace it everywhere the old secret was used. Source: [Human page](https://backlog.to/docs/web/automation/rotate-automation-secret) ###### What this page covers - Rotate intentionally. - Copy the new secret immediately. - Replace the old secret everywhere. ###### Walkthrough Use the automation settings page to rotate the credential only when rotation is truly required. ###### Touchpoints - Route: /workspace/settings/automation. Credential rotation surface. ###### Steps 1. Open the automation settings page and find the automation. 2. Trigger the rotation action and optionally add a helpful credential label. 3. Copy the new raw secret immediately. 4. Replace the old secret everywhere the automation still depends on it. ##### List Visible Agents Review the current visible agent bindings before creating a new agent or editing an existing one. Source: [Human page](https://backlog.to/docs/web/automation/list-agents) ###### What this page covers - Read the current agent inventory. - Choose the correct agent id. - Understand which installation each visible agent belongs to. ###### Walkthrough The automation settings page surfaces agents in the same place as their parent installations so attribution stays understandable. ###### Touchpoints - Route: /workspace/settings/automation. Automation settings page. ###### Steps 1. Open the automation settings page. 2. Review the visible agent section under the relevant installation. 3. Confirm the target binding id, name, and team scope before editing or creating anything else. 4. Move into create-agent or update-agent only after the current list is clear. ##### Create a Visible Agent Create a named visible agent under an existing installation so activity, assignees, and attribution can point to a meaningful product actor. Source: [Human page](https://backlog.to/docs/web/automation/create-agent) ###### What this page covers - Start from the correct installation. - Capture the returned profile id. - Choose the right team scope and role. ###### Walkthrough Use the automation settings page after the installation already exists. ###### Touchpoints - Route: /workspace/settings/automation. Visible-agent creation surface. ###### Steps 1. Open the automation settings page and locate the parent installation. 2. Start the visible-agent creation flow under that installation. 3. Provide the visible name, team scope, and role. 4. Save the agent and record the profile id if an external tool needs to select this agent explicitly. ##### Update a Visible Agent Change a visible agent name, team scope, role, or suspension state without recreating the binding. Source: [Human page](https://backlog.to/docs/web/automation/update-agent) ###### What this page covers - Find the correct binding id. - Apply the smallest valid update. - Keep attribution stable while maintenance happens. ###### Walkthrough The automation settings page is the contextual place to maintain visible agents over time. ###### Touchpoints - Route: /workspace/settings/automation. Visible-agent maintenance surface. ###### Steps 1. Open the automation settings page and find the visible agent under its parent installation. 2. Edit only the values that truly need to change: name, team scope, role, or suspension state. 3. Save the update and confirm the entry reflects the new state. 4. Return to the list view when the maintenance action is complete. ## API Authenticate clients, inspect workspace context, and automate work safely over the Backlog API. Source: [Human page](https://backlog.to/docs/api) ### Authenticate and Inspect Context Start sign-in, finish verification, and confirm the active workspace before you write data. #### Sign In and Sessions Start sign-in over REST, finish verification, and manage a human API session cleanly. Source: [Human page](https://backlog.to/docs/api/auth) ##### Overview Backlog uses one human sign-in model across the browser, API, and CLI. Use this topic when the reader needs to start sign-in, finish it, or manage the session after access has been issued. ##### What you can do - Request a sign-in or sign-up code. - Finish verification and land in the right surface. - Refresh or revoke a human session when needed. ##### Request a Sign-In Code Start the OTP flow and send a sign-in code to the correct email address. Source: [Human page](https://backlog.to/docs/api/auth/request-code) ###### What this page covers - Start the OTP flow correctly. - Use the correct purpose value for sign-in or sign-up. - Handle cooldowns and lockouts without guessing. ###### Walkthrough Start the OTP flow over REST so the user receives the right sign-in or sign-up code. ###### Touchpoints - Endpoint: POST /api/v1/auth/request-otp. Starts the OTP flow for a human principal. ###### Prerequisites - No bearer token is required for this call. ###### Steps 1. Send a JSON body with `email` and, optionally, `purpose`. 2. Use `signin` for an existing user flow or `signup` for a first-run flow. 3. Read the JSON response and capture the `expiresAt` value so the next step happens before the code expires. 4. If the server returns a cooldown or lockout response, wait for the provided retry window. ###### Notes - A valid email address is required. Invalid or blank email input fails immediately. ###### Request an OTP over REST ```bash curl -X POST http://localhost:5173/api/v1/auth/request-otp -H 'content-type: application/json' -d '{"email":"you@example.com","purpose":"signin"}' ``` ##### Verify the Sign-In Code Complete the OTP flow, establish the human session, and move into the workspace or terminal workflow. Source: [Human page](https://backlog.to/docs/api/auth/verify-code) ###### What this page covers - Submit the code in the correct place. - Capture the returned session tokens when using the API or CLI. - Land in the right post-verification surface. ###### Walkthrough Call the verify endpoint to exchange the code for a short-lived access token and a refresh token. ###### Touchpoints - Endpoint: POST /api/v1/auth/verify-otp. Verifies the code and mints a human API session. ###### Steps 1. Send `email`, `code`, and the same `purpose` value used when the OTP was requested. 2. Optionally include `name` for first-run identity creation and `label` for session naming. 3. Store the returned `accessToken` and `refreshToken` if the client needs to keep the session alive. 4. Use the returned bearer token on protected endpoints such as `/api/v1/me` and `/api/v1/workspaces/{workspaceId}/tasks`. ###### Notes - The server deletes the OTP after a successful verification. - An invalid code increments failure state and may eventually lock the flow temporarily. ###### Verify the code over REST ```bash curl -X POST http://localhost:5173/api/v1/auth/verify-otp -H 'content-type: application/json' -d '{"email":"you@example.com","code":"123456","purpose":"signin","label":"Local CLI"}' ``` ##### Refresh a Human Session Keep a human API session alive by exchanging the refresh token for a fresh token pair. Source: [Human page](https://backlog.to/docs/api/auth/refresh-session) ###### What this page covers - Refresh before expiry. - Replace stored tokens cleanly. - Know which auth session types can use refresh. ###### Important boundaries - Refresh is for human API sessions only. PATs and automation secrets do not use this flow. ###### Walkthrough Use the refresh endpoint with the current refresh token before the human session expires. ###### Touchpoints - Endpoint: POST /api/v1/auth/refresh. Refreshes a human API session. ###### Steps 1. Send the current `refreshToken` in the JSON body. 2. Receive a new access token and refresh token pair in the response. 3. Replace the previously stored tokens instead of keeping multiple versions around. 4. Retry protected requests with the fresh access token. ###### Refresh over REST ```bash curl -X POST http://localhost:5173/api/v1/auth/refresh -H 'content-type: application/json' -d '{"refreshToken":"refresh_token_here"}' ``` ##### Revoke a Human Session Invalidate a human API session explicitly instead of waiting for the access token to expire. Source: [Human page](https://backlog.to/docs/api/auth/revoke-session) ###### What this page covers - Invalidate a session deliberately. - Clear local credentials after revocation. - Avoid mixing session revocation with PAT rotation. ###### Important boundaries - Use PAT revocation for personal API keys and secret rotation for workspace automations. Do not use session revoke for those credential types. ###### Walkthrough Call the revoke endpoint with the bearer access token, the refresh token, or both. ###### Touchpoints - Endpoint: POST /api/v1/auth/revoke. Revokes a human API session. ###### Steps 1. Send the current bearer access token in the `Authorization` header when available. 2. Include the `refreshToken` in the request body when you still have it. 3. Wait for the success response before clearing local auth state. 4. Delete locally cached session tokens immediately after a successful revoke. #### Workspace Context Inspect the current principal and workspace before you run API calls with side effects. Source: [Human page](https://backlog.to/docs/api/workspace) ##### Overview This topic covers the authenticated workspace shell and the commands or endpoints that confirm the active workspace context. Use it when the next step depends on knowing which workspace, principal, or install boundary is active. ##### What you can do - Open the main workspace shell. - Confirm the current principal and workspace. - Check the active workspace before admin or automation work. ##### Inspect the Current Workspace Context Check who the current principal is, which workspace is active, and which installation context is in effect before you run sensitive automation or admin work. Source: [Human page](https://backlog.to/docs/api/workspace/inspect-current-context) ###### What this page covers - Identify the current principal. - Confirm the active workspace. - Prevent admin work in the wrong workspace. ###### Walkthrough Use the introspection endpoints before running scoped work that depends on the current principal or workspace. ###### Touchpoints - Endpoint: GET /api/v1/me. Returns the current principal, viewer, member, and workspace. - Endpoint: GET /api/v1/workspaces. Returns the visible workspace set for the current token. ###### Steps 1. Call `/api/v1/me` first to confirm whether the token resolved to a human or automation principal. 2. Read the `workspace` block to confirm the current workspace id, name, and context. 3. If the token is automation-backed, check the automation id, provider type, and allowed team ids before you issue write calls. 4. Call `/api/v1/workspaces` when you still need to resolve the workspace id for admin endpoints. ### Read and Change Work Read draft, task, and project data, then create or update work over REST. #### Draft Work Keep draft tasks visible in API reads when unfinished work still matters to automation. Source: [Human page](https://backlog.to/docs/api/draft) ##### Overview Drafts hold unfinished work that still needs review, cleanup, or a decision. Use this topic when the reader needs to understand what draft tasks are and what to do with them. ##### What you can do - Open the draft surface. - Review unfinished work. - Move from draft review back into active task work. ##### Review Draft Tasks Use the draft surface to inspect unfinished work before it joins the main task flow. Source: [Human page](https://backlog.to/docs/api/draft/review-drafts) ###### What this page covers - Open the draft route. - Understand why the work is still draft work. - Move from drafts into task execution. ###### Walkthrough Drafts can also be included in task collection reads when the client asks for them explicitly. ###### Touchpoints - Endpoint: GET /api/v1/workspaces/{workspaceId}/tasks?includeDrafts=true. Task list including drafts. ###### Steps 1. Call the tasks list endpoint with `includeDrafts=true`. 2. Read the combined task and draft task set returned by the endpoint. 3. Filter further by team, project, or status if the draft set is still too broad. 4. Patch the individual task through the task update route once you know what needs to change. #### Task Workflows Read, create, and update tasks over REST with explicit fields and clear intent. Source: [Human page](https://backlog.to/docs/api/task) ##### Overview Tasks are the main execution surface in the product. This topic breaks the work into clear task actions so the reader can go straight to the job they need. ##### What you can do - Pick the right task guide for the job at hand. - Create, inspect, and update tasks step by step. - Choose between browser, API, and CLI paths for the same action. ##### Browse Tasks Open the main task surface, narrow the visible list, and move from the collection view into the next task action. Source: [Human page](https://backlog.to/docs/api/task/browse) ###### What this page covers - Open the main task list. - Filter the collection correctly. - Move from the list into detail or creation. ###### Walkthrough Use the task collection endpoint when you need a bounded read of the current task set. ###### Touchpoints - Endpoint: GET /api/v1/workspaces/{workspaceId}/tasks. Task collection read. ###### Steps 1. Call `GET /api/v1/workspaces/{workspaceId}/tasks` with a bearer token that has `tasks.read`. 2. Add `teamId`, `projectId`, or `status` filters when the full visible set is too broad. 3. Read the returned task array and choose the task id you want to inspect or patch next. 4. Use the update route when the collection read tells you a field or status change is needed. ##### Create a Task Create a task with the right title, ownership, and optional planning context from the start. Source: [Human page](https://backlog.to/docs/api/task/create) ###### What this page covers - Use the right creation surface. - Fill required fields first. - Attach optional planning and ownership fields correctly. ###### Walkthrough Create a task over REST with the fields your workflow already knows and can justify. ###### Touchpoints - Endpoint: POST /api/v1/workspaces/{workspaceId}/tasks. Creates one task. ###### Steps 1. Send a bearer token with `tasks.write`. 2. Include at least `title` and `teamId` in the JSON body. 3. Add optional fields only when they are meaningful now: `description`, `projectId`, `milestoneId`, `assigneeId`, `deadlineAt`, `priority`, `status`, and `tags`. 4. Read the creation result and keep the new task id for the next step in the workflow. ###### Create a task over REST ```bash curl -X POST http://localhost:5173/api/v1/workspaces/ws_123/tasks -H 'authorization: Bearer access_token_here' -H 'content-type: application/json' -d '{"title":"Ship public docs","teamId":"team_123","priority":"high","status":"planned"}' ``` ##### Change Task Status Move a task through its status lifecycle without losing the activity trail that explains what changed and why. Source: [Human page](https://backlog.to/docs/api/task/change-status) ###### What this page covers - Choose a valid status. - Apply the transition from the correct surface. - Preserve a clean activity trail. ###### Walkthrough Use the task patch route when the status transition should come from an integration or automation. ###### Touchpoints - Endpoint: PATCH /api/v1/workspaces/{workspaceId}/tasks/{taskId}. Task patch endpoint. ###### Steps 1. Send a bearer token with `tasks.write`. 2. Pass the task id in the route path. 3. Send a JSON body containing only the new `status` when that is the only change. 4. Read the success response and then reload the task collection or detail page if you need the latest server state. ##### Update Task Details Change ownership, deadlines, labels, project links, description, or other mutable task fields without conflating that work with a status transition. Source: [Human page](https://backlog.to/docs/api/task/update-details) ###### What this page covers - Choose the correct mutation surface. - Use null-clears or clear actions correctly. - Keep the patch focused on the fields that truly changed. ###### Walkthrough Use the task patch route to change mutable fields beyond status. ###### Touchpoints - Endpoint: PATCH /api/v1/workspaces/{workspaceId}/tasks/{taskId}. Task patch endpoint. ###### Steps 1. Send only the fields that should change in the JSON body. 2. Use `null` for clearable fields such as `description`, `projectId`, `milestoneId`, `assigneeId`, or `deadlineAt` when the value should be removed. 3. If tags are included, send the full desired tag list rather than a partial append. 4. Keep status changes separate when you want the transition history to stay easy to read. #### Project Planning Read project collections and planning data over REST. Source: [Human page](https://backlog.to/docs/api/project) ##### Overview Projects are the planning surface for timing, ownership, health, and linked execution work. This topic separates project browsing, project detail, and roadmap reading so the reader can choose the right planning view. ##### What you can do - Browse the project list. - Inspect one project in detail. - Use the roadmap as a planning view. ##### Browse Projects Open the project index, narrow the project collection, and choose the next planning action. Source: [Human page](https://backlog.to/docs/api/project/browse) ###### What this page covers - Open the project index. - Filter by status or ownership. - Move from the index into project detail. ###### Walkthrough Use the project collection endpoint when you need a read-only project list in automation. ###### Touchpoints - Endpoint: GET /api/v1/workspaces/{workspaceId}/projects. Project collection read. ###### Steps 1. Send a bearer token with `projects.read`. 2. Add a `status` query parameter when the full visible collection is larger than necessary. 3. Read the project ids you need for related task creation or project navigation. 4. Switch to the browser project detail page when the list response is no longer enough. ### Manage Personal Access Create, review, and revoke personal tokens for human-owned automation. #### Sessions and Personal Tokens Create, list, and revoke personal tokens for human-owned API automation. Source: [Human page](https://backlog.to/docs/api/security) ##### Overview Security work is easier to follow when sessions and personal tokens are treated as separate jobs. This topic focuses on human-scoped credentials and session review, not workspace-shared automations. ##### What you can do - Review session state. - List personal tokens. - Create or revoke a personal token. ##### List Personal Access Tokens Review the current personal API keys before creating a new one or revoking an old one. Source: [Human page](https://backlog.to/docs/api/security/list-personal-access-tokens) ###### What this page covers - Open the correct PAT list surface. - Read current token status safely. - Use the list before create or revoke actions. ###### Walkthrough The list endpoint returns the current human user PAT inventory for review and cleanup. ###### Touchpoints - Endpoint: GET /api/v1/personal-access-tokens. Lists personal API keys for the current human. ###### Steps 1. Authenticate as a human principal with `tokens.manage`. 2. Call the list endpoint. 3. Read the returned credential ids, labels, scopes, and status fields. 4. Use those ids for a later revoke call if cleanup is needed. ##### Create a Personal Access Token Create a human-owned API key with the narrowest useful scope set and store it safely because the raw token is only shown once. Source: [Human page](https://backlog.to/docs/api/security/create-personal-access-token) ###### What this page covers - Choose scopes deliberately. - Copy the raw token immediately. - Use PATs only for human-owned automation. ###### Important boundaries - PATs belong to a human and never exceed the human role. They are not workspace-shared automation credentials. ###### Walkthrough The create endpoint issues the raw PAT once and stores only the hash at rest. ###### Touchpoints - Endpoint: POST /api/v1/personal-access-tokens. Creates a PAT. ###### Steps 1. Authenticate as a human principal with `tokens.manage`. 2. Send the label, optional scope list, and expiry days in the request body. 3. Read the returned token payload and capture the raw `token` field immediately. 4. Store the raw token securely in the system that will use it. ###### Create a PAT over REST ```bash curl -X POST http://localhost:5173/api/v1/personal-access-tokens -H 'authorization: Bearer access_token_here' -H 'content-type: application/json' -d '{"label":"Build server","expiresInDays":30,"scopes":["tasks.read","tasks.write","projects.read"]}' ``` ##### Revoke a Personal Access Token Revoke a human-owned API key by credential id when it is obsolete, leaked, or no longer appropriate for the workflow. Source: [Human page](https://backlog.to/docs/api/security/revoke-personal-access-token) ###### What this page covers - Find the right credential id first. - Use the correct revoke surface. - Confirm the key should no longer be used anywhere. ###### Walkthrough The revoke endpoint deletes the PAT by credential id for the current human principal. ###### Touchpoints - Endpoint: DELETE /api/v1/personal-access-tokens/{credentialId}. Revokes one PAT. ###### Steps 1. List the current PATs first if you do not already know the credential id. 2. Send the revoke request using the credential id in the path. 3. Wait for the success response. 4. Delete the raw token anywhere it may still be stored. ### Run Automation and Agents Exchange automation secrets, manage workspace automations, and control visible agents. #### Automation and Agents Exchange automation secrets, manage workspace automations, and control visible agents over REST. Source: [Human page](https://backlog.to/docs/api/automation) ##### Overview Workspace automations and visible agents are related, but they are not the same thing. This topic separates installation work from agent work so the reader can change the right object at the right time. ##### What you can do - Create and maintain workspace automations safely. - Exchange automation secrets correctly. - Create and update visible agents under an automation. ##### Exchange an Automation Secret Exchange an automation secret for an access token. Source: [Human page](https://backlog.to/docs/api/automation/exchange-automation-secret) ###### What this page covers - Use the right credential in the right place. - Mint a short-lived access token safely. - Know when to repeat the exchange. ###### Important boundaries - The long-lived automation secret is not the token you should keep reusing on normal resource endpoints. ###### Walkthrough Exchange the automation secret for an access token before calling scoped workspace APIs. ###### Touchpoints - Endpoint: POST /api/v1/automation-auth/exchange. Automation secret exchange endpoint. ###### Steps 1. Send the long-lived automation secret as the bearer token in the `Authorization` header. 2. Read the returned short-lived access token and expiry timestamp. 3. Use the short-lived access token on resource endpoints such as `/api/v1/workspaces/{workspaceId}/tasks` or `/api/v1/workspaces/{workspaceId}/projects`. 4. Repeat the exchange when the short-lived token expires. ###### Exchange an automation secret ```bash curl -X POST http://localhost:5173/api/v1/automation-auth/exchange -H 'authorization: Bearer blg_auto_secret_here' ``` ##### List Automations Review the current workspace automations before you create, update, or rotate one. Source: [Human page](https://backlog.to/docs/api/automation/list-automations) ###### What this page covers - Open the current automation inventory. - Choose the right automation id. - Avoid editing the wrong automation. ###### Walkthrough Use the workspace-scoped automation list endpoint when the reader needs automation ids or current automation state. ###### Touchpoints - Endpoint: GET /api/v1/workspaces/{workspaceId}/automations. Lists automations in one workspace. ###### Steps 1. Resolve the workspace id first. 2. Call the workspace automation list endpoint with a human token that has `workspace.automation.manage`. 3. Read the returned automation ids, scopes, and team boundaries. 4. Use the right automation id for the next create-agent, update-automation, or rotate-secret action. ##### Create an Automation Create the workspace automation boundary, issue the automation secret, and store that secret safely because it is only shown once. Source: [Human page](https://backlog.to/docs/api/automation/create-automation) ###### What this page covers - Create the automation boundary correctly. - Choose scopes and team limits deliberately. - Capture the secret safely the first time. ###### Walkthrough The automation create endpoint issues both the automation metadata and the raw secret once. ###### Touchpoints - Endpoint: POST /api/v1/workspaces/{workspaceId}/automations. Creates an automation. ###### Steps 1. Resolve the workspace id and authenticate as a human principal with `workspace.automation.manage`. 2. Send the automation create request with at least the name, then add provider type, team scope, scopes, and credential label as needed. 3. Read the returned automation id and raw secret payload. 4. Store the raw secret immediately in the system that will exchange or use it. ##### Update an Automation Change automation metadata, team boundaries, scopes, or suspension state without recreating the automation. Source: [Human page](https://backlog.to/docs/api/automation/update-automation) ###### What this page covers - Edit the correct automation. - Narrow scopes safely. - Suspend access without deleting context. ###### Walkthrough Use the automation patch endpoint when automation or admin tooling should change automation state. ###### Touchpoints - Endpoint: PATCH /api/v1/workspaces/{workspaceId}/automations/{automationId}. Updates an automation. ###### Steps 1. Identify the correct workspace id and automation id first. 2. Send only the fields that should change. 3. Use `description: null` when the description should be cleared. 4. Set `suspended` to `true` or `false` when the change is about access state rather than metadata. ##### Rotate an Automation Secret Issue a new automation secret when the old one should no longer be trusted, then replace it everywhere the old secret was used. Source: [Human page](https://backlog.to/docs/api/automation/rotate-automation-secret) ###### What this page covers - Rotate intentionally. - Copy the new secret immediately. - Replace the old secret everywhere. ###### Walkthrough The rotate endpoint returns the new raw secret once, so store it before leaving the response. ###### Touchpoints - Endpoint: POST /api/v1/workspaces/{workspaceId}/automations/{automationId}/rotate-secret. Rotates the secret. ###### Steps 1. Send the workspace id and automation id in the route path. 2. Optionally pass `credentialLabel` in the request body. 3. Read the returned raw secret from the response. 4. Replace the old secret and treat it as compromised or obsolete from that moment on. ##### List Visible Agents Review the current visible agent bindings before creating a new agent or editing an existing one. Source: [Human page](https://backlog.to/docs/api/automation/list-agents) ###### What this page covers - Read the current agent inventory. - Choose the correct agent id. - Understand which installation each visible agent belongs to. ###### Walkthrough Use the workspace agent list endpoint to read the current binding set. ###### Touchpoints - Endpoint: GET /api/v1/workspaces/{workspaceId}/agents. Lists visible agent bindings. ###### Steps 1. Resolve the workspace id first. 2. Call the agent list endpoint with a human token that has `workspace.automation.manage`. 3. Read the agent ids and installation relationships in the response. 4. Use the right agent id for later updates. ##### Create a Visible Agent Create a named visible agent under an existing installation so activity, assignees, and attribution can point to a meaningful product actor. Source: [Human page](https://backlog.to/docs/api/automation/create-agent) ###### What this page covers - Start from the correct installation. - Capture the returned profile id. - Choose the right team scope and role. ###### Walkthrough The create-agent endpoint binds a visible agent to an existing automation. ###### Touchpoints - Endpoint: POST /api/v1/workspaces/{workspaceId}/agents. Creates a visible agent binding. ###### Steps 1. Resolve the workspace id and the parent automation id first. 2. Send `automationId` and `name` in the request body, plus optional `teamIds` and `role`. 3. Read the returned binding id and profile id. 4. Store the profile id anywhere the app or CLI needs to select that visible agent later. ##### Update a Visible Agent Change a visible agent name, team scope, role, or suspension state without recreating the binding. Source: [Human page](https://backlog.to/docs/api/automation/update-agent) ###### What this page covers - Find the correct binding id. - Apply the smallest valid update. - Keep attribution stable while maintenance happens. ###### Walkthrough The patch endpoint updates an existing visible agent binding without recreating the installation relationship. ###### Touchpoints - Endpoint: PATCH /api/v1/workspaces/{workspaceId}/agents/{agentId}. Updates a visible agent binding. ###### Steps 1. Resolve the workspace id and agent id first. 2. Send only the changed fields in the request body. 3. Use `suspended` when the change is about temporary access state rather than naming or teams. 4. Read the success response and relist agents if you want to verify the current inventory. ## CLI Download the Backlog CLI, authenticate, inspect context, and run terminal-first workflows. Source: [Human page](https://backlog.to/docs/cli) ### Set Up the CLI Download the script, check local CLI state, save defaults, and switch auth modes cleanly. #### CLI Setup Download the CLI, inspect profile state, save defaults, and switch auth modes before you run repeated commands. Source: [Human page](https://backlog.to/docs/cli/cli) ##### Overview The Backlog CLI is shipped as a standalone shell script you can download directly from the public site. This topic holds the setup work that makes later task, project, security, and automation commands easier to run. ##### What you can do - Download the current CLI script. - Inspect the current CLI state. - Persist local profile defaults. - Switch the CLI into the correct auth mode. ##### Download the CLI Download the standalone Backlog CLI script from `https://backlog.to/backlog.sh` and make it executable locally. Source: [Human page](https://backlog.to/docs/cli/cli/download-cli) ###### Overview The Backlog CLI is distributed as a single shell script rather than a package manager install. That means the fastest path is to open `https://backlog.to/backlog.sh` or download it with `curl`, mark it executable, and run it from wherever you keep local tools. ###### What this page covers - Download the script directly. - Make the file executable. - Run the CLI locally before deeper setup. ###### Walkthrough The CLI is shipped as one downloadable shell script, so setup starts with saving `backlog.sh` locally and marking it executable. ###### Touchpoints - Public asset: https://backlog.to/backlog.sh. Open it in a browser or download it directly from the Backlog public site. - Command: curl -fsSL https://backlog.to/backlog.sh -o backlog.sh. Downloads the current CLI script. - Command: chmod +x backlog.sh. Makes the script executable. - Command: ./backlog.sh --help. Verifies the local script runs. ###### Steps 1. Open `https://backlog.to/backlog.sh` in a browser and save the file, or run `curl -fsSL https://backlog.to/backlog.sh -o backlog.sh` in the terminal. 2. Run `chmod +x backlog.sh` so the file can execute locally. 3. Run `./backlog.sh --help` to confirm the script starts correctly. 4. Keep using `./backlog.sh` directly, or move it into a directory already on your shell `PATH` if you want a shorter command later. ###### Notes - The public asset at `https://backlog.to/backlog.sh` always serves the current CLI script from the Backlog site. - The docs use `./backlog.sh` in examples, but the filename or final install location is up to you. ###### Shell example ```bash curl -fsSL https://backlog.to/backlog.sh -o backlog.sh chmod +x backlog.sh ./backlog.sh --help ``` ##### Check CLI Status Inspect the active CLI profile, token source, and workspace defaults before you run commands. Source: [Human page](https://backlog.to/docs/cli/cli/check-status) ###### What this page covers - See the active profile clearly. - Know which token is in use. - Catch a wrong workspace before acting. ###### Walkthrough Inspect the active CLI profile, token source, and stored workspace defaults before you continue. ###### Touchpoints - Command: ./backlog.sh status. Prints current CLI state. ###### Steps 1. Run `./backlog.sh status`. 2. Read the active profile, base URL, auth mode, and stored workspace id. 3. Check the token source so you know whether the CLI is using flags, environment, or stored secrets. 4. Only continue once the displayed state matches the workflow you intend to run. ##### Configure a CLI Profile Persist the base URL or workspace id for a CLI profile so repetitive commands stop depending on long flag strings. Source: [Human page](https://backlog.to/docs/cli/cli/configure-profile) ###### What this page covers - Persist stable defaults. - Clear stale local state when needed. - Reduce operator error in repetitive flows. ###### Walkthrough Profile configuration belongs in the local CLI profile, not in every repeated command invocation. ###### Touchpoints - Command: ./backlog.sh config set-base-url . Stores the base URL. - Command: ./backlog.sh config set-workspace . Stores the default workspace id. - Command: ./backlog.sh config clear-workspace. Removes the stored workspace id. - Command: ./backlog.sh config clear. Clears config, state, and stored secrets. ###### Steps 1. Store the base URL once with `./backlog.sh config set-base-url ` if you use the same environment repeatedly. 2. Store the workspace id with `./backlog.sh config set-workspace ` if you run workspace-scoped admin commands often. 3. Use `config clear-workspace` when the stored workspace id is the only stale value. 4. Use `config clear` when the whole profile should be reset to a clean state. ##### Set the Active CLI Token Switch the CLI into the right token mode before you run resource or admin commands. Source: [Human page](https://backlog.to/docs/cli/cli/set-token) ###### What this page covers - Load the correct token type. - Understand which flows need exchange. - Set a visible agent only when the token is automation-backed. ###### Walkthrough The CLI auto-detects token kind by prefix, so token loading is the main switch between auth modes. ###### Touchpoints - Command: ./backlog.sh auth set-token [TOKEN]. Loads the main bearer token. - Command: ./backlog.sh auth set-agent . Sets the visible agent profile id. - Command: ./backlog.sh auth clear-agent. Clears the visible agent profile id. ###### Steps 1. Run `./backlog.sh auth set-token blg_pat_xxx` when the CLI should act as a human PAT. 2. Run `./backlog.sh auth set-token blg_auto_xxx` when the CLI should act as a workspace installation, then exchange it before resource calls. 3. Run `./backlog.sh auth set-token blg_aat_xxx` when you already have an exchanged automation access token. 4. Set a linked visible agent only when the token is automation-backed and attribution should use that agent profile. ###### Notes - A configured visible agent is ignored for human tokens. ### Authenticate and Inspect Context Start sign-in, finish verification, and confirm the active workspace before you keep going. #### Sign In and Sessions Request sign-in codes, finish verification, and manage a human session from the terminal. Source: [Human page](https://backlog.to/docs/cli/auth) ##### Overview Backlog uses one human sign-in model across the browser, API, and CLI. Use this topic when the reader needs to start sign-in, finish it, or manage the session after access has been issued. ##### What you can do - Request a sign-in or sign-up code. - Finish verification and land in the right surface. - Refresh or revoke a human session when needed. ##### Request a Sign-In Code Start the OTP flow and send a sign-in code to the correct email address. Source: [Human page](https://backlog.to/docs/cli/auth/request-code) ###### What this page covers - Start the OTP flow correctly. - Use the correct purpose value for sign-in or sign-up. - Handle cooldowns and lockouts without guessing. ###### Walkthrough Trigger the OTP request from the CLI and continue into verification without switching tools. ###### Touchpoints - Command: ./backlog.sh auth request-otp [signin|signup]. Direct non-interactive command. - Command: ./backlog.sh auth wizard. Interactive access-mode chooser. ###### Prerequisites - `curl` and `jq` must be available on the local machine. ###### Steps 1. Run `./backlog.sh auth request-otp you@example.com signin` when you already know you need the OTP flow. 2. Use `signup` instead of `signin` when you are intentionally creating a new human identity. 3. Read the JSON result in the terminal and wait for the email to arrive. 4. Continue directly to code verification rather than rerunning the request command unnecessarily. ##### Verify the Sign-In Code Complete the OTP flow, establish the human session, and move into the workspace or terminal workflow. Source: [Human page](https://backlog.to/docs/cli/auth/verify-code) ###### What this page covers - Submit the code in the correct place. - Capture the returned session tokens when using the API or CLI. - Land in the right post-verification surface. ###### Walkthrough Verify the code from the terminal and let the CLI store the returned session tokens for the current profile. ###### Touchpoints - Command: ./backlog.sh auth verify-otp [options]. Verifies the code and persists the session. ###### Steps 1. Run `./backlog.sh auth verify-otp you@example.com 123456 --label "Local CLI"` after the code arrives. 2. Pass `--purpose signup` when the OTP request was made through the sign-up path. 3. Read the returned JSON and confirm that access and refresh tokens were issued. 4. Run `./backlog.sh me` next if you want to confirm the authenticated principal immediately. ##### Refresh a Human Session Keep a human API session alive by exchanging the refresh token for a fresh token pair. Source: [Human page](https://backlog.to/docs/cli/auth/refresh-session) ###### What this page covers - Refresh before expiry. - Replace stored tokens cleanly. - Know which auth session types can use refresh. ###### Important boundaries - Refresh is for human API sessions only. PATs and automation secrets do not use this flow. ###### Walkthrough Use the built-in CLI refresh command when the current profile already holds a human session. ###### Touchpoints - Command: ./backlog.sh auth refresh. Refreshes the stored human API session. ###### Steps 1. Make sure the current profile is using a human session rather than a PAT or automation token. 2. Run `./backlog.sh auth refresh`. 3. Let the CLI overwrite the stored access token and refresh token with the new pair. 4. Run `./backlog.sh status` if you want to confirm the new expiry timestamps. ##### Revoke a Human Session Invalidate a human API session explicitly instead of waiting for the access token to expire. Source: [Human page](https://backlog.to/docs/cli/auth/revoke-session) ###### What this page covers - Invalidate a session deliberately. - Clear local credentials after revocation. - Avoid mixing session revocation with PAT rotation. ###### Important boundaries - Use PAT revocation for personal API keys and secret rotation for workspace automations. Do not use session revoke for those credential types. ###### Walkthrough Use the built-in revoke command for the currently stored human session. ###### Touchpoints - Command: ./backlog.sh auth revoke. Revokes the current stored human session. ###### Steps 1. Confirm that the current auth mode is a human session rather than a PAT or automation token. 2. Run `./backlog.sh auth revoke`. 3. Let the CLI clear the access token, refresh token, and in-memory app access token state after success. 4. Run `./backlog.sh status` if you want to confirm the profile is now unauthenticated. #### Workspace Context Check the active principal and workspace context from the CLI before scoped or destructive work. Source: [Human page](https://backlog.to/docs/cli/workspace) ##### Overview This topic covers the authenticated workspace shell and the commands or endpoints that confirm the active workspace context. Use it when the next step depends on knowing which workspace, principal, or install boundary is active. ##### What you can do - Open the main workspace shell. - Confirm the current principal and workspace. - Check the active workspace before admin or automation work. ##### Inspect the Current Workspace Context Check who the current principal is, which workspace is active, and which installation context is in effect before you run sensitive automation or admin work. Source: [Human page](https://backlog.to/docs/cli/workspace/inspect-current-context) ###### What this page covers - Identify the current principal. - Confirm the active workspace. - Prevent admin work in the wrong workspace. ###### Walkthrough Use the CLI discovery commands plus status output before you do anything destructive or admin-scoped. ###### Touchpoints - Command: ./backlog.sh status. Shows local profile and auth state. - Command: ./backlog.sh me. Shows the current authenticated principal. - Command: ./backlog.sh workspaces. Lists visible workspaces. ###### Steps 1. Run `./backlog.sh status` to see the current profile, token source, and stored workspace id. 2. Run `./backlog.sh me` to confirm the principal type and current workspace context. 3. Run `./backlog.sh workspaces` if you need the workspace id for automation admin commands. 4. Persist the correct workspace id with `./backlog.sh config set-workspace ` before you continue. ### Work from the Terminal Read draft, task, and project data and make focused updates from the CLI. #### Draft Work List draft tasks in terminal workflows before you patch or promote the work. Source: [Human page](https://backlog.to/docs/cli/draft) ##### Overview Drafts hold unfinished work that still needs review, cleanup, or a decision. Use this topic when the reader needs to understand what draft tasks are and what to do with them. ##### What you can do - Open the draft surface. - Review unfinished work. - Move from draft review back into active task work. ##### Review Draft Tasks Use the draft surface to inspect unfinished work before it joins the main task flow. Source: [Human page](https://backlog.to/docs/cli/draft/review-drafts) ###### What this page covers - Open the draft route. - Understand why the work is still draft work. - Move from drafts into task execution. ###### Walkthrough Use the task list command with the draft flag when the terminal needs to include draft work. ###### Touchpoints - Command: ./backlog.sh tasks list --include-drafts. Task list that also includes drafts. ###### Steps 1. Run `./backlog.sh tasks list --include-drafts`. 2. Use additional filters such as `--team-id` or `--status` if the output is still too large. 3. Identify the task id that needs to be updated. 4. Use the task update command afterward to move the work forward. #### Task Workflows Create, list, and update tasks from the CLI without leaving the terminal. Source: [Human page](https://backlog.to/docs/cli/task) ##### Overview Tasks are the main execution surface in the product. This topic breaks the work into clear task actions so the reader can go straight to the job they need. ##### What you can do - Pick the right task guide for the job at hand. - Create, inspect, and update tasks step by step. - Choose between browser, API, and CLI paths for the same action. ##### Browse Tasks Open the main task surface, narrow the visible list, and move from the collection view into the next task action. Source: [Human page](https://backlog.to/docs/cli/task/browse) ###### What this page covers - Open the main task list. - Filter the collection correctly. - Move from the list into detail or creation. ###### Walkthrough Use the CLI list command when you want task collection reads in the terminal. ###### Touchpoints - Command: ./backlog.sh tasks list [options]. Task collection read in the CLI. ###### Steps 1. Run `./backlog.sh tasks list` for the default visible set. 2. Add `--team-id`, `--project-id`, or `--status` as needed. 3. Use the result to identify the task id or related project id you need next. 4. Continue with task create or task update rather than trying to do everything from the list output. ##### Create a Task Create a task with the right title, ownership, and optional planning context from the start. Source: [Human page](https://backlog.to/docs/cli/task/create) ###### What this page covers - Use the right creation surface. - Fill required fields first. - Attach optional planning and ownership fields correctly. ###### Walkthrough Use the CLI create command when you want a terminal-first creation flow. ###### Touchpoints - Command: ./backlog.sh tasks create [options]. Creates one task from the terminal. ###### Steps 1. Run `./backlog.sh tasks create --title "Ship public docs" --team-id team_123` as the minimum command. 2. Add optional flags such as `--description`, `--project-id`, `--assignee-id`, `--priority`, `--status`, or repeated `--tag` flags as needed. 3. Read the JSON response and keep the task id if a follow-up status or field change is coming next. 4. If the CLI is automation-backed, set the linked visible agent first when attribution matters. ##### Change Task Status Move a task through its status lifecycle without losing the activity trail that explains what changed and why. Source: [Human page](https://backlog.to/docs/cli/task/change-status) ###### What this page covers - Choose a valid status. - Apply the transition from the correct surface. - Preserve a clean activity trail. ###### Walkthrough Use the task update command with only the status flag when you want a clean status-only mutation in the terminal. ###### Touchpoints - Command: ./backlog.sh tasks update --status VALUE. Status-only task patch. ###### Steps 1. Find the task id first through `tasks list` if you do not already have it. 2. Run `./backlog.sh tasks update task_123 --status progressed`. 3. Review the JSON result and rerun `tasks list` if you need a visible confirmation. 4. Keep status-only changes separate from big field patches when readability matters. ##### Update Task Details Change ownership, deadlines, labels, project links, description, or other mutable task fields without conflating that work with a status transition. Source: [Human page](https://backlog.to/docs/cli/task/update-details) ###### What this page covers - Choose the correct mutation surface. - Use null-clears or clear actions correctly. - Keep the patch focused on the fields that truly changed. ###### Walkthrough Use the update command with the smallest set of flags that describe the real change. ###### Touchpoints - Command: ./backlog.sh tasks update [options]. General task patch command. ###### Steps 1. Run `./backlog.sh tasks update ` with only the field flags you need. 2. Use `--clear-description`, `--clear-project`, `--clear-milestone`, `--clear-assignee`, `--clear-deadline`, or `--clear-tags` when the goal is removal rather than replacement. 3. Use repeated `--tag` flags when you want to replace the full tag set with a new list. 4. Avoid sending an empty patch; the CLI already refuses it, and the workflow is easier to read when each command represents a real change. #### Project Planning Read projects and roadmap context from the CLI for planning and triage. Source: [Human page](https://backlog.to/docs/cli/project) ##### Overview Projects are the planning surface for timing, ownership, health, and linked execution work. This topic separates project browsing, project detail, and roadmap reading so the reader can choose the right planning view. ##### What you can do - Browse the project list. - Inspect one project in detail. - Use the roadmap as a planning view. ##### Browse Projects Open the project index, narrow the project collection, and choose the next planning action. Source: [Human page](https://backlog.to/docs/cli/project/browse) ###### What this page covers - Open the project index. - Filter by status or ownership. - Move from the index into project detail. ###### Walkthrough Use the project list command from the terminal when the goal is project discovery, not project mutation. ###### Touchpoints - Command: ./backlog.sh projects list [--status VALUE]. Read-only project list. ###### Steps 1. Run `./backlog.sh projects list` for the default visible set. 2. Add `--status active` or another status value when you know the project slice you need. 3. Read the project ids and names you need for follow-up work. 4. Move into the UI if the next step requires deeper project inspection or editing. ### Manage Personal Access Review, create, and revoke personal tokens from the terminal. #### Sessions and Personal Tokens Manage personal tokens from the CLI when local automation needs human-owned credentials. Source: [Human page](https://backlog.to/docs/cli/security) ##### Overview Security work is easier to follow when sessions and personal tokens are treated as separate jobs. This topic focuses on human-scoped credentials and session review, not workspace-shared automations. ##### What you can do - Review session state. - List personal tokens. - Create or revoke a personal token. ##### List Personal Access Tokens Review the current personal API keys before creating a new one or revoking an old one. Source: [Human page](https://backlog.to/docs/cli/security/list-personal-access-tokens) ###### What this page covers - Open the correct PAT list surface. - Read current token status safely. - Use the list before create or revoke actions. ###### Walkthrough The CLI list command is the fastest way to review human PATs from the terminal. ###### Touchpoints - Command: ./backlog.sh pat list. Lists current PATs. ###### Steps 1. Make sure the current auth mode is a human session with the right scope. 2. Run `./backlog.sh pat list`. 3. Review the token ids and status in the JSON output. 4. Choose the next action only after you know which credential id you are working with. ##### Create a Personal Access Token Create a human-owned API key with the narrowest useful scope set and store it safely because the raw token is only shown once. Source: [Human page](https://backlog.to/docs/cli/security/create-personal-access-token) ###### What this page covers - Choose scopes deliberately. - Copy the raw token immediately. - Use PATs only for human-owned automation. ###### Important boundaries - PATs belong to a human and never exceed the human role. They are not workspace-shared automation credentials. ###### Walkthrough The CLI create command can also immediately switch the current profile to the newly issued PAT. ###### Touchpoints - Command: ./backlog.sh pat create [options]. Creates a PAT from the terminal. ###### Steps 1. Run `./backlog.sh pat create` with a label and the narrowest set of repeated `--scope` flags you need. 2. Add `--use` if the current CLI profile should immediately start using the new PAT. 3. Capture the token output securely if you are not using `--use`. 4. Run `./backlog.sh status` afterward if you want to confirm the new auth mode. ##### Revoke a Personal Access Token Revoke a human-owned API key by credential id when it is obsolete, leaked, or no longer appropriate for the workflow. Source: [Human page](https://backlog.to/docs/cli/security/revoke-personal-access-token) ###### What this page covers - Find the right credential id first. - Use the correct revoke surface. - Confirm the key should no longer be used anywhere. ###### Walkthrough Use the PAT revoke command when the terminal already has the credential id. ###### Touchpoints - Command: ./backlog.sh pat revoke . Revokes one PAT. ###### Steps 1. Run `./backlog.sh pat list` if you still need to find the credential id. 2. Run `./backlog.sh pat revoke cred_123`. 3. Confirm the JSON response reports success. 4. Delete the raw PAT from any external secrets store or environment variable that still holds it. ### Run Automation and Agents Work with automation secrets, workspace automations, and visible agents from the CLI. #### Automation and Agents Exchange automation secrets and administer workspace automations or visible agents from the terminal. Source: [Human page](https://backlog.to/docs/cli/automation) ##### Overview Workspace automations and visible agents are related, but they are not the same thing. This topic separates installation work from agent work so the reader can change the right object at the right time. ##### What you can do - Create and maintain workspace automations safely. - Exchange automation secrets correctly. - Create and update visible agents under an automation. ##### Exchange an Automation Secret Exchange an automation secret for an access token. Source: [Human page](https://backlog.to/docs/cli/automation/exchange-automation-secret) ###### What this page covers - Use the right credential in the right place. - Mint a short-lived access token safely. - Know when to repeat the exchange. ###### Important boundaries - The long-lived automation secret is not the token you should keep reusing on normal resource endpoints. ###### Walkthrough Use the CLI exchange command after loading an automation secret into the active profile. ###### Touchpoints - Command: ./backlog.sh auth set-token blg_auto_xxx. Stores the automation secret. - Command: ./backlog.sh auth exchange [--save]. Exchanges the secret for a short-lived access token. ###### Steps 1. Store the automation secret with `./backlog.sh auth set-token blg_auto_xxx`. 2. Run `./backlog.sh auth exchange --save` if you want the CLI to persist the exchanged access token. 3. Read the returned access token metadata and expiry. 4. Run resource commands after the exchange so they use the short-lived access token instead of the long-lived secret. ##### List Automations Review the current workspace automations before you create, update, or rotate one. Source: [Human page](https://backlog.to/docs/cli/automation/list-automations) ###### What this page covers - Open the current automation inventory. - Choose the right automation id. - Avoid editing the wrong automation. ###### Walkthrough The CLI list command is the terminal path for reviewing automation inventory. ###### Touchpoints - Command: ./backlog.sh admin automations list [--workspace-id ID]. Lists automations for a workspace. ###### Steps 1. Store or pass the correct workspace id first. 2. Run `./backlog.sh admin automations list --workspace-id ws_123`. 3. Review the returned automation inventory carefully. 4. Choose the target automation id before you continue with update or rotate work. ##### Create an Automation Create the workspace automation boundary, issue the automation secret, and store that secret safely because it is only shown once. Source: [Human page](https://backlog.to/docs/cli/automation/create-automation) ###### What this page covers - Create the automation boundary correctly. - Choose scopes and team limits deliberately. - Capture the secret safely the first time. ###### Walkthrough The CLI create command can also store the newly issued secret as the active token when that is convenient for the next step. ###### Touchpoints - Command: ./backlog.sh admin automations create [options]. Creates an automation. ###### Steps 1. Run the create command with `--name` first, then add `--provider-type`, repeated `--team-id`, repeated `--scope`, and `--credential-label` if needed. 2. Add `--use` if the current CLI profile should immediately switch to the new automation secret. 3. Review the JSON response and capture the automation id. 4. Continue with exchange or visible-agent creation only after the secret is stored safely. ##### Update an Automation Change automation metadata, team boundaries, scopes, or suspension state without recreating the automation. Source: [Human page](https://backlog.to/docs/cli/automation/update-automation) ###### What this page covers - Edit the correct automation. - Narrow scopes safely. - Suspend access without deleting context. ###### Walkthrough The CLI update command handles the same automation maintenance work from the terminal. ###### Touchpoints - Command: ./backlog.sh admin automations update [options]. Updates an automation. ###### Steps 1. Run the update command with the automation id. 2. Add only the flags that describe the actual change: `--name`, `--description`, repeated `--team-id`, repeated `--scope`, `--suspend`, or `--unsuspend`. 3. Use `--clear-description` when the description should be removed. 4. Confirm the output and then re-list automations if you want a fresh inventory view. ##### Rotate an Automation Secret Issue a new automation secret when the old one should no longer be trusted, then replace it everywhere the old secret was used. Source: [Human page](https://backlog.to/docs/cli/automation/rotate-automation-secret) ###### What this page covers - Rotate intentionally. - Copy the new secret immediately. - Replace the old secret everywhere. ###### Walkthrough The CLI rotate command can also store the new secret as the active token when the next step stays in the terminal. ###### Touchpoints - Command: ./backlog.sh admin automations rotate [options]. Rotates the automation secret. ###### Steps 1. Run the rotate command with the automation id. 2. Add `--credential-label` if the new secret should have a specific label. 3. Add `--use` when the CLI profile should immediately switch to the new secret. 4. Replace the old secret in every external system that still holds it. ##### List Visible Agents Review the current visible agent bindings before creating a new agent or editing an existing one. Source: [Human page](https://backlog.to/docs/cli/automation/list-agents) ###### What this page covers - Read the current agent inventory. - Choose the correct agent id. - Understand which installation each visible agent belongs to. ###### Walkthrough The CLI list command is the terminal path for agent inventory review. ###### Touchpoints - Command: ./backlog.sh admin agents list [--workspace-id ID]. Lists visible agents in a workspace. ###### Steps 1. Pass or store the correct workspace id. 2. Run `./backlog.sh admin agents list --workspace-id ws_123`. 3. Review the binding ids and profile ids. 4. Continue to agent creation or update only after you know which agent record you are dealing with. ##### Create a Visible Agent Create a named visible agent under an existing installation so activity, assignees, and attribution can point to a meaningful product actor. Source: [Human page](https://backlog.to/docs/cli/automation/create-agent) ###### What this page covers - Start from the correct installation. - Capture the returned profile id. - Choose the right team scope and role. ###### Walkthrough The CLI create command can also immediately set the newly created visible agent as the active linked agent for the current profile. ###### Touchpoints - Command: ./backlog.sh admin agents create [options]. Creates a visible agent. ###### Steps 1. Run the create command with `--installation-id` and `--name` first. 2. Add repeated `--team-id` flags and `--role member` or `--role commentator` as needed. 3. Add `--use` if the current CLI profile should immediately adopt the new visible agent id. 4. Record the returned `profileId` for future automation-backed requests. ##### Update a Visible Agent Change a visible agent name, team scope, role, or suspension state without recreating the binding. Source: [Human page](https://backlog.to/docs/cli/automation/update-agent) ###### What this page covers - Find the correct binding id. - Apply the smallest valid update. - Keep attribution stable while maintenance happens. ###### Walkthrough The CLI update command is the terminal path for visible-agent maintenance. ###### Touchpoints - Command: ./backlog.sh admin agents update [options]. Updates a visible agent. ###### Steps 1. Run the update command with the target binding id. 2. Add only the flags that describe the intended change: `--name`, repeated `--team-id`, `--role`, `--suspend`, or `--unsuspend`. 3. Review the result and rerun the list command if you want to verify the full visible-agent inventory. 4. Keep the same profile id in downstream systems unless the binding itself was intentionally retired.