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

# Sign in as your agent

> Sign the CLI into an agent on your computer or a remote server.

[Install the CLI](/installation), then choose the agent whose email, SMS, and
secrets you want to use. The CLI saves one login at a time.

## Sign in on this computer

<Steps>
  <Step title="Sign in through your browser">
    ```bash theme={null}
    artil auth login
    ```

    The command opens a browser. Sign in, choose your workspace and agent,
    and approve the connection. The CLI checks and saves the login.

    Use a browser on the same computer as the CLI. If it cannot open one,
    the CLI prints a link to open yourself. For a remote server, follow
    [the token-login steps below](#use-a-headless-machine).
  </Step>

  <Step title="Check the agent">
    ```bash theme={null}
    artil auth status
    ```

    Check that status shows the agent and workspace you chose. It also shows
    the agent's email address when email is set up. You can see the same
    information by running `artil` and choosing **Status**.

    Artil grants message permissions when it sets up the agent's first channel.
    If an email or SMS command fails, follow
    [message troubleshooting](/troubleshooting#email-or-sms-is-unavailable).
  </Step>
</Steps>

<Card title="Next: read and reply to an email" href="/email">
  Send a test message to the address shown in status, then read it from the terminal.
</Card>

## Use a headless machine

Use a token when the CLI runs on a server without a browser. A token is a
password-like credential that lets the CLI act as an existing agent.

For example, to use an agent called **Support Bot** on a remote server:

<Steps>
  <Step title="On your laptop: create the token">
    Open Artil in your browser, select the workspace, and open **Support Bot**.
    Click **Connect agent account**, then **Create a token** in the sign-in step.

    Copy the command before closing the dialog. It contains the token, which
    is shown only once. The command looks like this:

    ```bash theme={null}
    artil auth login --token "YOUR_COPIED_TOKEN"
    ```

    `YOUR_COPIED_TOKEN` is a placeholder. Use the full command copied from the app.
  </Step>

  <Step title="On the server: run the copied command">
    Connect to the server where you installed the CLI and run the command.
    The CLI checks the token and saves the login without opening a browser.

    Check the result:

    ```bash theme={null}
    artil auth status
    ```

    Status should show **Support Bot** and its workspace. Later commands use
    this saved login, so you only need to supply the token once.

    The copied command contains a secret and may remain in shell history.
    Keep it out of shared logs and agent conversations.
  </Step>
</Steps>

For scripts, you can also create an agent token from
[Tokens](https://app.artil.dev/tokens): choose **Create token**, give it a name,
and select the agent. Set `ARTIL_TOKEN` in the environment, then run
`artil auth login` to save it. Other commands use the saved login.

## Manage a login

<AccordionGroup>
  <Accordion title="Switch agents">
    Run `artil auth login` again and choose the other agent in the browser.
    A new browser login replaces and revokes this machine's previous browser
    login on the same Artil server.

    The Claude Code plugin and Pi extension use the newly saved login.
    Start a new Claude Code or Pi session after switching agents.
    If you set up automatic delivery with `artil init`, run it again for the
    newly selected agent to review the connection and its linked secrets.
  </Accordion>

  <Accordion title="Use account access">
    To request access as your account instead of one agent:

    ```bash theme={null}
    artil auth login --account
    ```

    For commands that need an agent, specify it:

    ```bash theme={null}
    artil init --agent <agent>
    artil secrets list --agent <agent>
    ```

    Use a name, slug, or ID. If more than one agent has that name, use its slug
    or ID. Email, SMS, and agent MCP setup require an agent login.

    `--account` opens browser approval. A token already has its own permissions,
    so you cannot combine `--account` with a token.
  </Accordion>

  <Accordion title="Use another Artil server">
    Login defaults to `https://app.artil.dev`. For a different server:

    ```bash theme={null}
    artil auth login --url https://app.example.com
    ```

    You can also set the login URL with `ARTIL_BASE_URL`; `--url` overrides it.
    After login, commands use the saved server address. Create tokens in the
    same Artil server you want to sign in to.
  </Accordion>

  <Accordion title="Sign out of this computer">
    If you also want to remove message delivery setup, follow
    [disconnect message delivery](/automatic-messages#change-or-disconnect-a-client)
    before signing out. That step uses `artil init --client none`, which also
    removes the agent's remote Hermes webhook, even if another computer
    configured it.

    To remove the saved login:

    ```bash theme={null}
    artil auth logout
    ```

    Logout also removes the MCP entries installed by the CLI. The agent's
    remote Hermes webhook stays configured. The server token and any copied
    secrets remain valid.
    Revoke a manually created token on **Tokens**, or a browser authorization
    on the app's [Clients screen](https://app.artil.dev/clients), to end access.

    Remove copied secrets with `artil secrets unlink <place>` and stop programs
    that already loaded them.

    Credentials are stored in `~/.config/artil/credentials.json` with private
    file permissions. Do not copy this file into a repository or conversation.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.