install: open the dashboard sign-in page from the CLI (#90)

Onboarding starts on the web, since the GitHub App install lives there. Give
callers one command that gets them to the right page instead of a URL they
have to be told. The link is built from the active host's app base, so a beta
or self-hosted CLI does not send its user to prod.

Author: hbrooks

README.md

@@ -40,6 +40,7 @@ skills:
 ## Usage
 
 ```sh
+agent install                     # open the dashboard sign-in page, where you install Ellipsis
 agent login                       # device-code auth against the active host
 agent logout                      # remove stored credentials (--all for every host)
 agent me                          # show the current credential's identity

skills/ellipsis/SKILL.md

@@ -45,14 +45,15 @@ sandbox image actually builds, then deploy. The steps below are that flow.
 
    ```sh
    brew install ellipsis-dev/cli/agent
+   agent install    # opens the dashboard sign-in page, where you install Ellipsis
    agent login      # device-code flow tied to your GitHub identity
    agent ping       # confirms the CLI can authenticate and reach the API
    ```
 
    Sessions clone real repositories, so the GitHub App must be installed on
-   the account (app.ellipsis.dev walks through it). In CI or another headless
-   environment, export an API key as `ELLIPSIS_API_TOKEN` instead of logging
-   in.
+   the account. `agent install` opens the page that walks through it. In CI or
+   another headless environment, export an API key as `ELLIPSIS_API_TOKEN`
+   instead of logging in.
 
 2. See a session run before configuring anything:
 

src/cli.tsx

@@ -1,4 +1,5 @@
 import { Command } from 'commander'
+import { registerInstall } from './commands/install'
 import { registerLogin } from './commands/login'
 import { registerHost } from './commands/host'
 import { registerMe } from './commands/me'
@@ -33,6 +34,7 @@ program
 // rendering (sorted, alias-free, grouped at the top level).
 configureCliHelp(program)
 
+registerInstall(program)
 registerLogin(program)
 registerHost(program)
 registerMe(program)

src/commands/install.ts

@@ -0,0 +1,19 @@
+import type { Command } from 'commander'
+import { resolveAppBase } from '../lib/config'
+import { openBrowser } from '../lib/auth'
+import { appLoginUrl } from '../lib/urls'
+
+export function registerInstall(program: Command): void {
+  program
+    .command('install')
+    .description('Open the dashboard sign-in page, where you install Ellipsis')
+    .option('--no-browser', 'print the URL without opening a browser (for headless or SSH)')
+    .action((opts: { browser?: boolean }) => {
+      const url = appLoginUrl(resolveAppBase())
+      console.log('To install Ellipsis, open this URL and sign in:')
+      console.log(`  ${url}`)
+      if (opts.browser !== false) {
+        openBrowser(url)
+      }
+    })
+}

src/lib/help.ts

@@ -23,7 +23,7 @@ const TOP_LEVEL_GROUPS: ReadonlyArray<{ title: string; commands: readonly string
   { title: 'Platform', commands: ['variable', 'asset', 'hook'] },
   { title: 'Integrations', commands: ['integration', 'github', 'slack', 'linear', 'sentry'] },
   { title: 'Spend', commands: ['budget', 'usage', 'analytics'] },
-  { title: 'Account', commands: ['login', 'logout', 'me', 'host', 'ping'] },
+  { title: 'Account', commands: ['install', 'login', 'logout', 'me', 'host', 'ping'] },
 ]
 
 export function configureCliHelp(program: Command): void {

src/lib/urls.ts

@@ -25,6 +25,13 @@ export function cliAuthUrl(appBase: string, userCode: string): string {
   return `${appBase}/cli-auth?code=${encodeURIComponent(userCode)}`
 }
 
+// The dashboard sign-in page, where a new customer installs the Ellipsis
+// GitHub App. Built from the active host's app base for the same reason as
+// cliAuthUrl: a beta or self-hosted CLI must not send its user to prod.
+export function appLoginUrl(appBase: string): string {
+  return `${appBase}/login`
+}
+
 // Wrap `label` in an OSC 8 hyperlink so it opens `url` on click in terminals
 // that support it (iTerm2, VS Code, WezTerm, kitty, GNOME); degrades to plain
 // text elsewhere. Only emitted to a TTY — piped output stays free of escapes.

test/urls.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { cliAuthUrl, configUrl, hyperlink, sessionUrl } from '../src/lib/urls'
+import { appLoginUrl, cliAuthUrl, configUrl, hyperlink, sessionUrl } from '../src/lib/urls'
 
 describe('sessionUrl', () => {
   it('builds the account page link with the session query param', () => {
@@ -37,6 +37,18 @@ describe('cliAuthUrl', () => {
   })
 })
 
+describe('appLoginUrl', () => {
+  it('builds the dashboard sign-in page url', () => {
+    expect(appLoginUrl('https://app.ellipsis.dev')).toBe('https://app.ellipsis.dev/login')
+  })
+
+  it('tracks the app base host, so a beta base yields a beta sign-in url', () => {
+    expect(appLoginUrl('https://beta-app.ellipsis.dev')).toBe(
+      'https://beta-app.ellipsis.dev/login',
+    )
+  })
+})
+
 describe('hyperlink', () => {
   const ESC = String.fromCharCode(27)