> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate with CLI agents

> Create a CLI app with Stytch Authentication.

In this guide, we'll walk through the creation of a simple Command Line Interface application which utilizes Stytch Connected Apps for authentication via an existing web application.

This guide will reference two example apps:

* [stytch-react-example](https://github.com/stytchauth/stytch-react-example) - used as the base web app that will authorize the CLI app.
* [stytch-connected-apps-cli-example](https://github.com/stytchauth/stytch-connected-apps-cli-example) - a basic CLI app made with Cobra.

Feel free to pull down both of these example repositories to follow along and run through this guide!

Users will initiate authorization from within the CLI, redirect to the web app, authorize the CLI app from within the web app, and then be redirected back to the CLI where a Connected Apps `access_token` will be minted.

## Pre-requisites

In order to complete this guide, you'll need:

* A Stytch project. If you don't have one already, or would like to create a new one, in the [Dashboard](https://stytch.com/dashboard), click on your existing project name in the top left corner of the Dashboard, click Create Project, and then select Consumer Authentication.
* A web app that uses Stytch for authentication (this guide will use [stytch-react-example](https://github.com/stytchauth/stytch-react-example)).
* A basic CLI app (this guide will use [stytch-connected-apps-cli-example](https://github.com/stytchauth/stytch-connected-apps-cli-example)).

## Create a CLI app

<Steps>
  <Step title="Create a Connected App">
    Navigate to the Connected Apps section of your Stytch Dashboard, and create a new Connected App.

    <img src="https://mintcdn.com/stytch-34ca0595/cD8BioQ2Qs_VMTqe/images/connected-apps/getting-started/create-new-app.png?fit=max&auto=format&n=cD8BioQ2Qs_VMTqe&q=85&s=11e817caef56f1761414197198f785f2" alt="Create New App" width="3000" height="1500" data-path="images/connected-apps/getting-started/create-new-app.png" />

    Configure the app as First Party Public.

    <img src="https://mintcdn.com/stytch-34ca0595/cD8BioQ2Qs_VMTqe/images/connected-apps/getting-started/select-client-type.png?fit=max&auto=format&n=cD8BioQ2Qs_VMTqe&q=85&s=e239e1517fefc7d82dd72757a08470f7" alt="Select Client Type" width="3000" height="1500" data-path="images/connected-apps/getting-started/select-client-type.png" />

    Add `http://127.0.0.1/callback` as a login redirect URL in the Connected App configuration - this is the URL our CLI app will use to receive the authorization `code`.

    Omitting a port in the redirect URL permits any port to be used, allowing the CLI application to use dynamic port allocation. We want to dynamically allocate a free port, as opposed to picking a static one, as we don't know what conflicting processes may be running on our end users device.

    <img src="https://mintcdn.com/stytch-34ca0595/FB84jLh1Rx_Ls_jG/images/connected-apps/guides/cli-app-1.png?fit=max&auto=format&n=FB84jLh1Rx_Ls_jG&q=85&s=6bb9a265f44f574a83bc81a137a7e988" alt="Cli App 1" width="3000" height="1500" data-path="images/connected-apps/guides/cli-app-1.png" />

    Set the authorization URL in Connected Apps page to `http://localhost:3000/oauth/authorize` - this is the URL that our web app will expose to mount the `<IdentityProvider /> `component for authorization.

    <img src="https://mintcdn.com/stytch-34ca0595/FB84jLh1Rx_Ls_jG/images/connected-apps/guides/cli-app-2.png?fit=max&auto=format&n=FB84jLh1Rx_Ls_jG&q=85&s=a4912bbca7317afb0211e3865a759571" alt="Cli App 2" width="3000" height="1500" data-path="images/connected-apps/guides/cli-app-2.png" />
  </Step>

  <Step title="Add an authorization route to your web app">
    Add a route in your web app that mounts the `<IdentityProvider />` component.

    In [stytch-react-example](https://github.com/stytchauth/stytch-react-example), we do this [here](https://github.com/stytchauth/stytch-react-example/blob/main/src/components/Authorize.tsx):

    ```javascript theme={null}
    import { IdentityProvider, useStytchUser } from '@stytch/react';
    import { useEffect } from 'react';

    const Authorize = () => {
      const { user } = useStytchUser();

      useEffect(() => {
        if (!user) {
          window.location.href = '/';
        }
      }, [user]);

      return <IdentityProvider />;
    };

    export default Authorize;
    ```
  </Step>

  <Step title="Configure CLI app to initiate authorization flow with PKCE">
    To initiate the authorization flow, configure your CLI app to navigate to your web app's page that mounts `<IdentityProvider />`.

    The list of URL parameters required for this request can be found [here](/connected-apps/build-login-flow/login-flow).

    * If you'd like to receive a `refresh_token`, allowing your CLI app to refresh the `access_token` without the user re-authorizing, make sure your request includes `scope=offline_access`.
    * Because this is a public Connected App, we need to use PKCE rather than a `client_secret`, as there is nowhere to securely store a `client_secret`. The PKCE `code_challenge` and `code_challenge_method` will be sent along as part of the initiating request.

    In [stytch-connected-apps-cli-example](https://github.com/stytchauth/stytch-connected-apps-cli-example), we do this in `cmd/auth.go`.

    Relevant snippets below:

    ```go theme={null}
    // Get a free port for the callback server
    port := utils.GetOpenPort()
    redirectURI := fmt.Sprintf("http://127.0.0.1:%d/callback", port)

    // Generate PKCE values
    codeVerifier, err := generateCodeVerifier()

    if err != nil {
    	fmt.Printf("Error generating code verifier: %v\n", err)
    	return
    }

    codeChallenge := generateCodeChallenge(codeVerifier)

    // Construct the auth URL with PKCE parameters
    params := url.Values{}
    params.Add("client_id", clientID)
    params.Add("redirect_uri", redirectURI)
    params.Add("response_type", "code")
    params.Add("code_challenge", codeChallenge)
    params.Add("code_challenge_method", "S256")
    params.Add("scope", "offline_access")

    authURL := fmt.Sprintf("%s?%s", authorizeURL, params.Encode())

    fmt.Println("Opening browser for authentication...")

    // Open the browser with the auth URL
    err = openBrowser(authURL)
    if err != nil {
    fmt.Println("Please open the following URL in your browser:", authURL)
    }
    ```
  </Step>

  <Step title="Handle callback and exchange code for access token">
    Next, set up a callback handler in your CLI app that authenticates the authorization `code` received back from `<IdentityProvider />` via the [Get Access Token endpoint](/api-reference/consumer/api/m2m/token/get-access-token).

    Note that we need to include `code_verifier` in this call since this is a Public app.

    In [stytch-connected-apps-cli-example](https://github.com/stytchauth/stytch-connected-apps-cli-example), we do this in `cmd/auth.go`:

    ```go theme={null}
    // Channel to receive the auth code
    codeChan := make(chan string)
    errorChan := make(chan error)

    // Set up the callback handler
    http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) {
    	code := r.URL.Query().Get("code")
    	if code == "" {
    		errorChan <- fmt.Errorf("no code received in callback")
    		return
    	}

    	// Send success response to browser
    	w.Write([]byte("Authentication successful! You can close this window."))
    	codeChan <- code
    })

    // Start the server in a goroutine
    go func() {
    	if err := server.ListenAndServe(); err != http.ErrServerClosed {
    		errorChan <- err
    	}
    }()

    // Wait for either the code or an error
    var code string
    select {
    case code = <-codeChan:
    	fmt.Println("Received authorization code")
    case err := <-errorChan:
    	fmt.Printf("Error: %v\n", err)
    	return
    case <-time.After(5 * time.Minute):
    	fmt.Println("Timeout waiting for authentication")
    	return
    }

    // Exchange the code for a token
    token, err := exchangeCodeForToken(code, codeVerifier)

    // Save the tokens to keyring
    utils.SaveToken(token.AccessToken, utils.AccessToken)
    utils.SaveToken(token.RefreshToken, utils.RefreshToken)

    // Shutdown the server
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    server.Shutdown(ctx)
    ```

    `exchangeCodeForToken()` in the above snippet is implemented [here](https://github.com/stytchauth/stytch-connected-apps-cli-example/blob/main/cmd/auth.go#L146), and calls the [Get Access Token endpoint](/api-reference/consumer/api/m2m/token/get-access-token) with:

    1. The `code` retrieved by the channel set up,
    2. The `code_verifier` generated at the start of the authorization flow
    3. The Connected App's `client_id`
    4. `grant_type`: “authorization\_code” because this is an initial authorization flow and not a refresh flow.

    The access and refresh tokens returned should be stored securely, where other CLI applications or tools cannot access them. The example above uses a helper called `utils.saveToken`, which utilizes go keyring.

    ```go theme={null}
    // SaveToken persists the token securely
    func SaveToken(tok string, typ TokenType) error {
    	return keyring.Set(service, user+string(typ), tok)
    }
    ```
  </Step>

  <Step title="Testing">
    To test the flow with the example apps above:

    1. Set up and run stytch-react-example locally, following the instructions in the README.
    2. Authenticate into the example app, so that you have an active Session.
    3. Run [stytch-connected-apps-cli-example](https://github.com/stytchauth/stytch-connected-apps-cli-example), following the instructions in the README.
    4. You should be automatically redirected to the authorization flow in your browser, redirect back to your CLI, and see a Connected Apps `access_token`!
  </Step>

  <Step title="Next steps">
    Now that you're authenticated with a Connected Apps `access_token` in your CLI app, your backend can authenticate API requests by verifying this token.

    For example, if your CLI app calls `GET https://yourapp.com/api/resources` to take some action in your app/platform, attaching the `access_token` as a Bearer token, your backend can perform authentication via something like the following:

    ```go theme={null}
    func resourcesHandler(w http.ResponseWriter, r *http.Request) {
    	auth := r.Header.Get("Authorization")
    	if !strings.HasPrefix(auth, "Bearer ") {
    		http.Error(w, "Unauthorized", http.StatusUnauthorized)
    		return
    	}
    	token := strings.TrimPrefix(auth, "Bearer ")

    	resp, err := stytchClient.IDP.IntrospectTokenLocal(r.Context(), &idp.IntrospectTokenLocalParams{
    		Token: token,
    	})
    	if err != nil || !resp.TokenActive {
    		http.Error(w, "Unauthorized", http.StatusUnauthorized)
    		return
    	}

    	// Token is valid — respond with protected data
    	w.WriteHeader(http.StatusOK)
    	w.Write([]byte(`{"message": "Authenticated!"}`))
    }
    ```
  </Step>
</Steps>