> ## 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.

# FAQ

> Common questions about JoyStream, agents, credentials, and the CLI.

## Getting started

<AccordionGroup>
  <Accordion title="Do I need to be a developer to use JoyStream?">
    No. You describe what you want in conversation and JoyStream turns it into a specification, a reviewable plan, and a safe run. That's the point of the product — the person who owns the work should be able to build and evolve the agent that does it.

    The CLI is one way to reach the platform. The web UI is another.
  </Accordion>

  <Accordion title="What's the difference between jstm and joystream?">
    They are the same program. The prebuilt binary is named `joystream`; `jstm` is the short alias. Use whichever you prefer.
  </Accordion>

  <Accordion title="Which platforms is the CLI built for?">
    CI currently builds a macOS arm64 binary. On other platforms, build from source with `make build`, which names the binary for your platform automatically. See [Install the CLI](/installation).
  </Accordion>

  <Accordion title="macOS won't run the downloaded binary.">
    macOS quarantines binaries downloaded from the internet. Clear the attribute and run it again:

    ```bash theme={null}
    xattr -cr ./joystream
    ```
  </Accordion>
</AccordionGroup>

## Building agents

<AccordionGroup>
  <Accordion title="I exited the planning chat. Did I lose my work?">
    No. Exiting always leaves your spec as a draft — that's deliberate, so a closed terminal can never create or change an agent by accident.

    Resume with `jstm agent plan <session-id>`, or commit with `jstm agent plan done <session-id>`.
  </Accordion>

  <Accordion title="I lost the session id.">
    ```bash theme={null}
    jstm agent plan list
    ```

    It shows your sessions newest first, with their status.
  </Accordion>

  <Accordion title="Typing 'save' in the chat didn't save anything.">
    Correct. `save`, `done`, `quit`, and `exit` all only exit the chat. The only command that commits is `jstm agent plan done <session-id>`, run after you leave.
  </Accordion>

  <Accordion title="Can I run the planning chat in a script or CI?">
    Not the chat itself — it requires a real interactive terminal and fails fast rather than degrading.

    To create a draft non-interactively:

    ```bash theme={null}
    jstm agent plan --new --json
    ```
  </Accordion>

  <Accordion title="What's the difference between conform and readiness?">
    Conformance asks whether the built package is well-formed against the agent spec. Readiness asks whether the skills it needs can actually execute here — servers reachable, credentials present.

    A package can be perfectly conformant and completely unable to run.
  </Accordion>

  <Accordion title="Does conform need an API key?">
    No. The CLI runs the two deterministic lanes, `schema` and `spec_conflict`, which need no key and no network. The semantic `judge` lane is optional and isn't run by the CLI.
  </Accordion>
</AccordionGroup>

## Running agents

<AccordionGroup>
  <Accordion title="What's the difference between Dry Run, Pilot, and Live?">
    Dry Run executes end to end with side-effecting actions held back — nothing outside JoyStream changes. Pilot is controlled real execution with limited scope, access, volume, or audience. Live is approved production execution.

    Pilot and Live both prompt for confirmation.
  </Accordion>

  <Accordion title="What was Sandbox?">
    The earlier name for Dry Run. The stage is the same.
  </Accordion>

  <Accordion title="A run finished but nothing happened downstream.">
    Check the mode. Dry Run holds side effects back by design.

    ```bash theme={null}
    jstm agent status failed-payment-digest
    ```
  </Accordion>

  <Accordion title="My run says completed but a step failed.">
    A `BEST_EFFORT` step records its failure and lets the run continue, so a run can complete with a failure inside it. Check the stories, not only the run status.

    ```bash theme={null}
    jstm agent stories failed-payment-digest --status failed
    ```
  </Accordion>

  <Accordion title="Can I stop a run from starting twice?">
    Pass an idempotency key. Re-sending the same key won't start a second run.

    ```bash theme={null}
    jstm agent run failed-payment-digest --idempotency-key digest-2026-08-03
    ```
  </Accordion>

  <Accordion title="The output stream stopped after a few minutes.">
    The stream times out after 300 seconds. The run keeps going — rejoin with `jstm agent run show`.
  </Accordion>
</AccordionGroup>

## Scheduling and triggers

<AccordionGroup>
  <Accordion title="My 09:00 schedule fires at the wrong time.">
    All schedules are evaluated in UTC. There is no per-schedule timezone in this version, so `0 9 * * *` means 09:00 UTC.
  </Accordion>

  <Accordion title="My live schedule silently went back to dry runs.">
    `schedule set` sends the run mode on every call and defaults it to `dry_run`. Changing only `--cron` reverts a live schedule.

    Always repeat `--env live`:

    ```bash theme={null}
    jstm agent schedule set 8c41f2b9-… --cron "0 9 * * 1" --env live
    ```
  </Accordion>

  <Accordion title="The platform was down. Will I get a burst of missed runs?">
    No. It fires the most recent missed occurrence once on recovery, then resumes normally.
  </Accordion>

  <Accordion title="Does schedule take an agent id?">
    No, an installation id. Get it from `jstm agent installations`.
  </Accordion>
</AccordionGroup>

## Credentials and access

<AccordionGroup>
  <Accordion title="Why does my agent act as me instead of as the team?">
    A personal credential is shadowing the shared one. Credentials resolve from the most specific tier outward — personal, then workspace, then org.

    ```bash theme={null}
    jstm connection resolve github --workspace acme-corp/finance
    ```
  </Accordion>

  <Accordion title="Signing in with GitHub doesn't let me read private repos.">
    That sign-in grants public access only. Private repositories need a personal access token with the `repo` scope, connected under Settings → Connections.
  </Accordion>

  <Accordion title="Can an org admin see my personal credentials?">
    No. Personal vaults are excluded from the org audit entirely.
  </Accordion>

  <Accordion title="Can anyone see a credential's value?">
    No surface returns token material — not the API, not the CLI, not the UI. You see providers, status, and who connected them, never secrets.
  </Accordion>

  <Accordion title="Where did vault grant and revoke go?">
    They were replaced by `vault scope`, which sets a credential's availability in one choice: `--scope all` for org-wide, or `--scope selected` with repeatable `--workspace`.

    `vault grants` still exists, as a read.
  </Accordion>
</AccordionGroup>

## Teams and sharing

<AccordionGroup>
  <Accordion title="Someone accepted a share. What did they get?">
    Membership in the workspace, as a `member` — not scoped to the shared object alone. Share deliberately.
  </Accordion>

  <Accordion title="Can I share something from my personal workspace?">
    No. Move it to a team workspace first:

    ```bash theme={null}
    jstm agent move failed-payment-digest --to acme-corp/finance
    ```
  </Accordion>

  <Accordion title="How long does a share link last?">
    Seven days. There is no never-expires option. Resending resets the clock.
  </Accordion>

  <Accordion title="What happens to agents when someone leaves?">
    Agents in a team workspace stay. Agents in their personal workspace leave with them — which is why work that matters to the team should be moved to a team workspace early.

    After removing someone, run `jstm vault audit` and reconnect any credential they had connected.
  </Accordion>

  <Accordion title="Two workspaces have the same handle.">
    Team handles are unique within an organization, not across all of them.

    ```bash theme={null}
    jstm workspace resolve platform --org acme-corp
    ```

    Or use the fully qualified form, `acme-corp/platform`.
  </Accordion>

  <Accordion title="Should I use visibility or sharing?">
    Visibility (`ORG_VISIBLE`) is for a capability the whole organization should find and install. Sharing is for one person and one object.
  </Accordion>
</AccordionGroup>

## The CLI

<AccordionGroup>
  <Accordion title="Is --json a global flag?">
    No, it's per command. Most read and write commands support it. A few don't, because their output is interactive or a single line — `connection test`, `connection add`, `connection remove`, `triggers delete`, `triggers webhook-url`, `org invite`, `org remove`, the `profile emails` subcommands, and `jstm commands`.
  </Accordion>

  <Accordion title="Can I pipe --json output safely?">
    Yes. Results go to stdout and all diagnostics to stderr, so the JSON stream stays clean:

    ```bash theme={null}
    jstm agent list --json | jq '.[].handle'
    ```
  </Accordion>

  <Accordion title="Why did a command exit 2?">
    A usage error — an unknown flag, a missing argument, or an invalid command form. A bare `jstm agent plan` is the common one; creating an agent is always explicit.
  </Accordion>

  <Accordion title="How do I point the CLI at a different backend?">
    ```bash theme={null}
    export JOYSTREAM_API_URL=https://api.example.com
    ```

    For a fully separate login, also set `JOYSTREAM_CONFIG_DIR`. See [Configuration](/cli/configuration).
  </Accordion>

  <Accordion title="How do I authenticate in CI?">
    Set `JOYSTREAM_TOKEN`. It takes precedence over the session file, so no interactive login is needed.
  </Accordion>

  <Accordion title="How do I see the whole command surface?">
    ```bash theme={null}
    jstm commands
    ```

    It always reflects the version you have installed.
  </Accordion>
</AccordionGroup>

## Still stuck?

Email [support@joystream.ai](mailto:support@joystream.ai), and include the output of `JOYSTREAM_DEBUG=1 jstm <your command>`.