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

# Quickstart

> Draft, build, and dry-run your first agent from the terminal.

This takes you from a signed-in terminal to a working agent that has completed a run with no production side effects. It should take about ten minutes.

## Prerequisites

* The `jstm` CLI installed. See [Install the CLI](/installation).
* A real interactive terminal. The planning chat won't run in a pipe or in CI.

<Steps>
  <Step title="Sign in">
    ```bash theme={null}
    jstm login
    jstm whoami
    ```

    `whoami` shows your user and your active workspace. Everything you create lands in that workspace.
  </Step>

  <Step title="Draft the agent">
    ```bash theme={null}
    jstm agent plan --new
    ```

    A chat opens and asks what the agent should do. Describe it in plain language:

    ```text theme={null}
    Every weekday morning, pull yesterday's failed payments from Stripe
    and post a summary to our #billing Slack channel.
    ```

    Joyvis drafts a spec and asks follow-up questions — which Slack workspace, what counts as a failure, who to notify if Stripe is unreachable. Keep going until the plan looks right.

    Type `/` at the start of a message to search the skills catalog and reference one directly.

    When you're done, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. The chat prints your session id.

    ```text theme={null}
      Session: 5f3a…-9b21 — spec is DRAFT (not committed).
      Resume editing:  jstm agent plan 5f3a…-9b21
      Commit the spec: jstm agent plan done 5f3a…-9b21
    ```

    <Note>
      Exiting never commits. Your spec stays a draft until the next step, so a closed terminal or a dropped connection can't create an agent by accident.
    </Note>
  </Step>

  <Step title="Commit the draft">
    ```bash theme={null}
    jstm agent plan done 5f3a5c81-2d44-4e0b-9a17-0c9d3b7e9b21
    ```

    This is the step that creates the agent. It saves the spec, promotes it, and prints the resulting work tree.

    Lost the session id? `jstm agent plan list` shows your sessions.
  </Step>

  <Step title="Build a package">
    ```bash theme={null}
    jstm agent build
    ```

    Build compiles the committed spec into an immutable, versioned package and waits for it to finish. The receipt tells you the version it produced.
  </Step>

  <Step title="Check it against the spec">
    ```bash theme={null}
    jstm agent conform ./failed-payment-digest
    ```

    Conformance reads the built package and reports any place it violates the agent spec, each finding citing the clause it breaks. It needs no API key and no network.

    Exit `0` means clean. Exit `1` means there is at least one blocking problem — see [Reading the flag report](/features/conformance/flag-report).
  </Step>

  <Step title="Dry-run it">
    ```bash theme={null}
    jstm agent dry-run acme-corp/failed-payment-digest
    ```

    This stages the agent at Dry Run and fires one run. The agent executes end to end, but side-effecting actions are held back — nothing is posted to Slack, nothing is changed in Stripe.

    Progress streams as it happens, story by story. When it finishes you get a run id.
  </Step>

  <Step title="Read what happened">
    ```bash theme={null}
    jstm agent run show acme-corp/failed-payment-digest/runs/1
    jstm ticket list --agent-id acme-corp/failed-payment-digest
    ```

    `run show` gives you the run's status, its stories, its output, and the exact versions that executed. `ticket list` shows the same work as tickets — the business-readable view a teammate can read without knowing anything about the CLI.

    This is the evidence you'll use to decide whether the agent is ready for real traffic.
  </Step>
</Steps>

## What you have now

An agent that exists as a versioned, inspectable package, has been checked against the spec, and has completed a full execution without touching anything real.

It has not been promoted. Dry Run is where it stays until you decide otherwise.

## Next

<Columns cols={2}>
  <Card title="Promote to production" href="/guides/promote-to-production" icon="rocket">
    Move through Pilot to Live, deliberately.
  </Card>

  <Card title="Schedule it" href="/guides/schedule-an-agent" icon="clock">
    Run it on a recurring cron schedule.
  </Card>

  <Card title="Connect a service" href="/guides/connect-a-service" icon="plug">
    Give the agent real credentials for Stripe and Slack.
  </Card>

  <Card title="How JoyStream thinks" href="/concepts/overview" icon="compass">
    Why the lifecycle is shaped this way.
  </Card>
</Columns>

Need help? Email [support@joystream.ai](mailto:support@joystream.ai).