1"use strict";(globalThis.webpackChunkdocs=globalThis.webpackChunkdocs||[]).push([[2673],{416(e,t,n){n.d(t,{R:()=>a,x:()=>l});var s=n(9471);const i={},r=s.createContext(i);function a(e){const t=s.useContext(r);return s.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:a(e.components),s.createElement(r.Provider,{value:t},e.children)}},3601(e,t,n){n.r(t),n.d(t,{assets:()=>o,contentTitle:()=>l,default:()=>d,frontMatter:()=>a,metadata:()=>s,toc:()=>h});const s=JSON.parse('{"id":"cli/auth","title":"auth","description":"Browser-based OAuth authentication for integrations","source":"@site/docs/cli/auth.md","sourceDirName":"cli","slug":"/cli/auth","permalink":"/docs/cli/auth","draft":false,"unlisted":false,"editUrl":"https://github.com/multivmlabs/ralph-starter/tree/main/docs/docs/cli/auth.md","tags":[],"version":"current","sidebarPosition":7,"frontMatter":{"sidebar_position":7,"title":"auth","description":"Browser-based OAuth authentication for integrations","keywords":["cli","auth","command","oauth","authentication","linear","notion","github"]},"sidebar":"docsSidebar","previous":{"title":"task","permalink":"/docs/cli/task"},"next":{"title":"setup","permalink":"/docs/cli/setup"}}');var i=n(2615),r=n(416);const a={sidebar_position:7,title:"auth",description:"Browser-based OAuth authentication for integrations",keywords:["cli","auth","command","oauth","authentication","linear","notion","github"]},l="ralph-starter auth",o={},h=[{value:"Synopsis",id:"synopsis",level:2},{value:"Description",id:"description",level:2},{value:"Arguments",id:"arguments",level:2},{value:"Options",id:"options",level:2},{value:"Supported Services",id:"supported-services",level:2},{value:"Examples",id:"examples",level:2},{value:"Start OAuth Flow (Linear)",id:"start-oauth-flow-linear",level:3},{value:"Check Authentication Status",id:"check-authentication-status",level:3},{value:"Logout from a Service",id:"logout-from-a-service",level:3},{value:"Configure Manual API Keys",id:"configure-manual-api-keys",level:3},{value:"Show Help",id:"show-help",level:3},{value:"OAuth PKCE Flow",id:"oauth-pkce-flow",level:2},{value:"Setting Up Linear OAuth",id:"setting-up-linear-oauth",level:3},{value:"Exit Codes",id:"exit-codes",level:2},{value:"See Also",id:"see-also",level:2}];function c(e){const t={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.header,{children:(0,i.jsx)(t.h1,{id:"ralph-starter-auth",children:"ralph-starter auth"})}),"\n",(0,i.jsx)(t.p,{children:"Browser-based OAuth authentication for integrations. Supports OAuth PKCE flows for services like Linear, and manages manual API key configuration for services like Notion and GitHub."}),"\n",(0,i.jsx)(t.h2,{id:"synopsis",children:"Synopsis"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"ralph-starter auth [service]\nralph-starter auth --list\nralph-starter auth --logout <service>\n"})}),"\n",(0,i.jsx)(t.h2,{id:"description",children:"Description"}),"\n",(0,i.jsxs)(t.p,{children:["The ",(0,i.jsx)(t.code,{children:"auth"})," command manages authentication credentials for ralph-starter's integrations. It operates in three modes:"]}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"OAuth Flow"})," -- Start a browser-based OAuth PKCE flow for a supported service (e.g., Linear)."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Status Listing"})," -- Show authentication status for all services."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Logout"})," -- Remove stored credentials for a service."]}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"Credentials are stored locally in the ralph-starter sources configuration file."}),"\n",(0,i.jsx)(t.h2,{id:"arguments",children:"Arguments"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Argument"}),(0,i.jsx)(t.th,{children:"Description"})]})}),(0,i.jsx)(t.tbody,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"service"})}),(0,i.jsxs)(t.td,{children:["The service to authenticate with (e.g., ",(0,i.jsx)(t.code,{children:"linear"}),", ",(0,i.jsx)(t.code,{children:"notion"}),", ",(0,i.jsx)(t.code,{children:"github"}),")"]})]})})]}),"\n",(0,i.jsx)(t.h2,{id:"options",children:"Options"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Option"}),(0,i.jsx)(t.th,{children:"Description"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"--list"})}),(0,i.jsx)(t.td,{children:"Show authentication status for all services"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"--logout <service>"})}),(0,i.jsx)(t.td,{children:"Remove credentials for the specified service"})]})]})]}),"\n",(0,i.jsx)(t.h2,{id:"supported-services",children:"Supported Services"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Service"}),(0,i.jsx)(t.th,{children:"Auth Method"}),(0,i.jsx)(t.th,{children:"Details"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"linear"})}),(0,i.jsx)(t.td,{children:"Browser OAuth (PKCE)"}),(0,i.jsxs)(t.td,{children:["Seamless browser-based flow. Requires ",(0,i.jsx)(t.code,{children:"RALPH_LINEAR_CLIENT_ID"})," env var."]})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"notion"})}),(0,i.jsx)(t.td,{children:"Manual API key"}),(0,i.jsxs)(t.td,{children:["Set via ",(0,i.jsx)(t.code,{children:"ralph-starter config set notion.apiKey <key>"}),". Get key at ",(0,i.jsx)(t.a,{href:"https://www.notion.so/my-integrations",children:"notion.so/my-integrations"}),"."]})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:(0,i.jsx)(t.code,{children:"github"})}),(0,i.jsx)(t.td,{children:"Manual API key"}),(0,i.jsxs)(t.td,{children:["Set via ",(0,i.jsx)(t.code,{children:"ralph-starter config set github.apiKey <key>"}),". Get token at ",(0,i.jsx)(t.a,{href:"https://github.com/settings/tokens",children:"github.com/settings/tokens"}),"."]})]})]})]}),"\n",(0,i.jsx)(t.h2,{id:"examples",children:"Examples"}),"\n",(0,i.jsx)(t.h3,{id:"start-oauth-flow-linear",children:"Start OAuth Flow (Linear)"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# Authenticate with Linear via browser OAuth\nralph-starter auth linear\n"})}),"\n",(0,i.jsx)(t.p,{children:"This opens your browser, completes the PKCE authorization flow, and stores the token locally. The flow uses a local callback server with a 5-minute timeout."}),"\n",(0,i.jsx)(t.h3,{id:"check-authentication-status",children:"Check Authentication Status"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"ralph-starter auth --list\n"})}),"\n",(0,i.jsx)(t.p,{children:"Output:"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:"Authentication Status\nCredentials stored in: /
1home/user/.config/ralph-starter/sources.json\n\n \u2713 Linear - Authenticated\n \u25cb Notion - Manual API key\n Run: ralph-starter config set notion.apiKey <your-key>\n \u25cb GitHub - Manual API key\n Run: ralph-starter config set github.apiKey <your-key>\n"})}),"\n",(0,i.jsx)(t.h3,{id:"logout-from-a-service",children:"Logout from a Service"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# Remove stored credentials for Linear\nralph-starter auth --logout linear\n"})}),"\n",(0,i.jsx)(t.h3,{id:"configure-manual-api-keys",children:"Configure Manual API Keys"}),"\n",(0,i.jsx)(t.p,{children:"For services that do not support OAuth PKCE, configure API keys manually:"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# Notion\nralph-starter config set notion.apiKey ntn_your_api_key_here\n\n# GitHub\nralph-starter config set github.apiKey ghp_your_github_token\n"})}),"\n",(0,i.jsx)(t.h3,{id:"show-help",children:"Show Help"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# Run auth with no arguments to see help\nralph-starter auth\n"})}),"\n",(0,i.jsx)(t.h2,{id:"oauth-pkce-flow",children:"OAuth PKCE Flow"}),"\n",(0,i.jsx)(t.p,{children:"For services that support PKCE (currently Linear), the authentication process works as follows:"}),"\n",(0,i.jsxs)(t.ol,{children:["\n",(0,i.jsx)(t.li,{children:"A local callback server starts on a random port."}),"\n",(0,i.jsx)(t.li,{children:"A PKCE challenge and CSRF state token are generated."}),"\n",(0,i.jsx)(t.li,{children:"Your browser opens to the service's authorization URL."}),"\n",(0,i.jsx)(t.li,{children:"After you authorize, the callback server receives the authorization code."}),"\n",(0,i.jsx)(t.li,{children:"The code is exchanged for access (and optionally refresh) tokens using the PKCE verifier."}),"\n",(0,i.jsx)(t.li,{children:"Tokens are stored locally."}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"If the browser cannot be opened automatically, the authorization URL is printed for manual use."}),"\n",(0,i.jsx)(t.h3,{id:"setting-up-linear-oauth",children:"Setting Up Linear OAuth"}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# 1. Set your Linear OAuth client ID\nexport RALPH_LINEAR_CLIENT_ID=your_client_id\n\n# 2. Run the auth flow\nralph-starter auth linear\n\n# 3. Verify\nralph-starter auth --list\n"})}),"\n",(0,i.jsxs)(t.p,{children:["Get a Linear client ID from ",(0,i.jsx)(t.a,{href:"https://linear.app/settings/api/applications",children:"linear.app/settings/api/applications"}),"."]}),"\n",(0,i.jsx)(t.h2,{id:"exit-codes",children:"Exit Codes"}),"\n",(0,i.jsxs)(t.table,{children:[(0,i.jsx)(t.thead,{children:(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.th,{children:"Code"}),(0,i.jsx)(t.th,{children:"Description"})]})}),(0,i.jsxs)(t.tbody,{children:[(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"0"}),(0,i.jsx)(t.td,{children:"Success"})]}),(0,i.jsxs)(t.tr,{children:[(0,i.jsx)(t.td,{children:"1"}),(0,i.jsx)(t.td,{children:"Unknown service, OAuth not configured, or authentication failed"})]})]})]}),"\n",(0,i.jsx)(t.h2,{id:"see-also",children:"See Also"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.a,{href:"/docs/cli/config",children:"ralph-starter config"})," - Manage configuration including API keys"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.a,{href:"/docs/cli/integrations",children:"ralph-starter integrations"})," - List and test integrations"]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.a,{href:"/docs/cli/auto",children:"ralph-starter auto"})," - Use authenticated sources for batch processing"]}),"\n"]})]})}function d(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.