# Get Crystl on Your iPhone!
Manage and schedule your agents when you're out and about. [Learn more](/content/features/mobile/index.html)

The agent in your shard can run the `crystl` command. That means it can look things up, report on your workspace, and (with a [Guild membership](/content/pricing/index.html)) set the workspace up for you.

This is the fastest way to learn crystl. Instead of reading a page about a feature, ask the agent sitting in front of you.

## It Already Knows the Commands
crystl maintains a CLI reference inside each gem’s `CLAUDE.md` or `AGENTS.md`, so a fresh agent in a fresh gem starts out knowing the commands exist. You do not have to paste anything.

That is the **tell agents about the crystl CLI** setting, on by default, under settings, **agents > defaults**. Turning it off stops new writes but leaves blocks already written in your projects in place. It does take crystl’s short section out of `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. See [agent files](/content/docs/agent-files/index.html).

An agent can also tell whether it is inside crystl at all: the `CRYSTL_SHARD` environment variable is non-empty in a shard and unset everywhere else.

## Ask It to Look Things Up
`crystl docs` is the whole documentation set, in the terminal, and it is **free on every tier**.

> Ask your agent: _“what does crystl’s in gem approval mode actually allow? check `crystl docs`.”_

It runs something like:

```
crystl docs approval          # search
crystl docs approval-modes    # read the page
```

Every page includes its crystl.dev URL, so the agent can hand you a link to the same page in your browser.

This is worth knowing before you start reading docs yourself: your agent can answer most crystl questions without you leaving the shard, and it will quote the version of the docs that matches what it can see.

> **Why the answer is sometimes a little old.** The `crystl docs` CLI caches the index for six hours, so just after a docs update the terminal may serve a slightly older page than the website. Ask again tomorrow, or open the URL.

## Ask It What Your Workspace Is Doing
Also free, also read-only:

```
crystl status              # everything, including memory pressure
crystl shards --all        # every shard in every gem, and who needs a person
crystl history search "…"  # find that thing you said three days ago
```

`crystl shards --all` is the one to remember. It leads with the shards that want a human, and for agents that report turn ends it says what each one’s last turn was: `❓ needs you`, `✓ declared done`, or `⚠ turn failed`. A quiet shard is not a finished shard, and that command is how you tell the difference in one call.

> Ask your agent: _“is anything waiting on me right now?”_

## Let It Hand You Things

```
crystl copy "the thing you need"
```

Anything you would otherwise drag-select out of wrapped terminal lines goes to a one-click copy bar instead. Free on every tier. A well-behaved agent reaches for this on its own for tokens, URLs, and especially commands it wants you to run.

If it copies something that reads as a command to run, the CLI says so on the spot and names `crystl card --action-command`, which gives you a button instead. Six commands teach like that, each only when the situation calls for it: see [the CLI page](/content/docs/cli/#the-cli-teaches-a-better-next-move/index.html). You will see those lines in your terminal too, prefixed `crystl:`, and `CRYSTL_NO_TEACH=1` turns them off.

`crystl card "…"` gets your attention with a notification, on the desktop and on your phone.

## Let It Set Up Your Workspace
These are [Guild](/content/pricing/index.html) commands, because they change things rather than read them.

```
crystl open ~/Projects/other-repo        # open a gem
crystl shard create --gem myapp --prompt "add tests"   # spawn a worker
crystl merge                              # integrate a finished worker's branch
```

The useful moment is mid-task. Your agent notices the bug is actually in a sibling repo, opens that project as its own gem, and carries on, without you stopping to do it by hand.

From there, one session can manage several: see [fanout](/content/docs/fanout/index.html) and the [orchestration guide](/content/docs/orchestration-guide/index.html).

On the free tier these return `403 guild_required`. A good agent will tell you that is what happened rather than working around it.

## What It Cannot Do
- **Change what you have not approved.** Driving crystl is not a way around [approval modes](/content/docs/approval-modes/index.html). The same rules apply to an agent’s tool calls whether or not it also uses the CLI.
- **Message a crown.** In a [court](/content/docs/court/index.html), only you may talk to the crown. An agent’s `send` into one is refused and pointed at the hand instead.
- **Speak for another agent.** Commands report where they came from, and a shard cannot call off another shard’s [vigil](/content/docs/vigil/index.html) watch or answer its questions.

## Where to Go Next
- [crystl CLI](/content/docs/cli/index.html) for the full command reference and the tier breakdown.
- [Getting started](/content/docs/getting-started/index.html) if you have not created a gem yet.
- [Fanout](/content/docs/fanout/index.html) for one agent managing several.
