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

# Quickstart

> Create an S2 account, install the CLI, and start appending and reading streams right away.

## Onboarding

**First**, log in to the [dashboard](https://s2.dev/dashboard), create a new organization and issue an access token.

## Get started with the CLI

<Steps>
  <Step title="Install the S2 CLI">
    <Tabs>
      <Tab title="Using Homebrew">
        This method works on macOS and Linux distributions with
        [Homebrew](https://brew.sh) installed.

        Homebrew 6.0 and later require explicit [tap trust](https://docs.brew.sh/Tap-Trust) for third-party taps. Installing with the fully qualified name trusts only the S2 formula:

        ```bash theme={null}
        brew install s2-streamstore/s2/s2
        ```

        <Note>
          The fully qualified name (`s2-streamstore/s2/s2`) scopes trust to that formula only. To trust every current and future package in the tap instead, run `brew trust s2-streamstore/s2` before installing.
        </Note>
      </Tab>

      <Tab title="Using Cargo">
        This method works on any system with [Rust](https://www.rust-lang.org/)
        and [Cargo](https://doc.rust-lang.org/cargo/) installed.

        ```bash theme={null}
        cargo install --locked s2-cli
        ```
      </Tab>

      <Tab title="From Release Binaries">
        Check out the [S2 CLI Releases](https://github.com/s2-streamstore/s2/releases?q=s2-cli\&expanded=true)
        for prebuilt binaries for many different architectures and operating systems.

        Linux and macOS users can download the release binary using:

        ```bash theme={null}
        curl -fsSL s2.dev/install.sh | bash
        ```

        <Note>
          The script will install the binary in `~/.s2/bin` and modify
          the shell profile file to add it to the path. Make sure to
          reload the shell or open up a new terminal after completing
          the installation.
        </Note>
      </Tab>
    </Tabs>

    The binary should be installed as `s2`.
  </Step>

  <Step title="Persist your access token">
    ```bash theme={null}
    s2 config set access_token YOUR_ACCESS_TOKEN
    ```
  </Step>

  <Step title="Create a new basin">
    <Tip>
      Basin names must be globally unique. Try creating a basin with your
      GitHub handle, something like `username-first-basin`.
    </Tip>

    <Info>
      A basin name must be between 8 and 48 characters long and comprise
      lowercase letters, numbers and hyphens. It cannot begin or end with a
      hyphen.
    </Info>

    ```bash theme={null}
    export BASIN="YOUR_BASIN_NAME"
    s2 create-basin ${BASIN}
    ```

    Let's double-check that the new basin is active. You should see its name in the list with an `active` status:

    ```bash theme={null}
    s2 list-basins
    ```
  </Step>

  <Step title="Grab your popcorn!">
    Nothing better than Star Wars to give us a good sense of how we can exercise `append` and `read` sessions, and see what **data in motion** looks like.

    We will start by creating a new stream called `starwars`.

    ```bash theme={null}
    s2 create-stream s2://${BASIN}/starwars
    ```

    Some of you may have watched the movie in ASCII over telnet from `towel.blinkenlights.nl`!

    We will do the same, except we will "append" the movie to our `starwars` stream while we also tail it.

    Start by creating a read session like so:

    ```bash theme={null}
    s2 read s2://${BASIN}/starwars 2> /dev/null
    ```

    Open another terminal and start an append session:

    ```bash theme={null}
    export BASIN="YOUR_BASIN_NAME" # Set the basin name for new terminal
    nc starwars.s2.dev 23 | s2 append s2://${BASIN}/starwars
    ```

    <div data-cast="https://s2.dev/recordings/starwars-append.cast" data-rows="20" data-autoplay="true" data-loop="true" />

    Go back to the previous terminal with the read session to enjoy the movie:

    <div data-cast="https://s2.dev/recordings/starwars-read.cast" data-rows="20" data-autoplay="true" data-loop="true" />
  </Step>
</Steps>

## What You Just Used

You just created a [basin](/concepts/basins), wrote to a [stream](/concepts/streams), and moved [records](/concepts/records) with [appends](/concepts/appends) and [reads](/concepts/reads).

<CardGroup cols={2}>
  <Card title="Explore S2 concepts" icon="book-open" href="/concepts/records">
    Start with records, then follow the model through streams, basins, appends, and reads.
  </Card>

  <Card title="Try more demos" icon="play" href="/demos">
    Explore the playground, resumable AI chat, live sandbox logs, and collaborative editing.
  </Card>
</CardGroup>