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

# Sign in as your agent

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

[Install the CLI](/installation), then choose the agent account 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.
    A browser sign-in expires after 30 days, and then you sign in again;
    tokens created in the app don't expire.

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

    If an email or SMS command fails, follow
    [message troubleshooting](/troubleshooting#email-or-sms-is-unavailable).
  </Step>
</Steps>

<Card title="Next: choose a client" href="/setup">
  Connect Claude Code, Codex, Pi, OpenClaw, Hermes, or ChatGPT to this agent's inbox.
</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 to agent**, choose a CLI harness such as **Claude Code**,
    and click **Use a token**. Enter a token name, such as the server's name,
    and click **Create token**.

    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 a token from the agent's **Tokens** tab: open
the agent, select **Tokens**, click **New token** and **Use a token**, enter a
name, and click **Create token**. Set `ARTIL_TOKEN` to the token in the command
it shows. Every command then signs in with it, ahead of the saved login, and
nothing is saved on disk, which suits a container that gets the token as a
secret. Run `artil auth login` to save it instead.

## Manage a login

<AccordionGroup>
  <Accordion title="Switch agents">
    Run `artil auth login` again and choose the other agent in the browser.
    The new login replaces the saved one. If your previous browser login from
    this computer was in the same workspace, Artil also revokes it; one from
    another workspace keeps working until it expires.

    The Claude Code, Codex, and OpenClaw plugins and the Pi package use the
    newly saved login. Start a new Claude Code or Pi session, or run
    `openclaw gateway restart`, 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 secrets list --agent <agent>
    artil init --client hermes --connection server --agent <agent>
    ```

    Use a name, slug, or ID. If more than one agent matches, use the ID; the
    error lists each match with its ID. An agent login is needed for email and
    SMS, for `artil secrets copy`, `code`, `link`, and `pull`, and for `artil init`
    with Claude Code, Pi, or Hermes on this computer.

    `--account` opens browser approval. A token's access is set when it is
    created, so you cannot combine `--account` with a token.
  </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 a remote Hermes webhook set up from this computer.

    To remove the saved login:

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

    Logout also removes the `artil-messages` channel from Claude Code and the
    `artil-messages` extension from Pi, and stops Hermes runs on this computer.
    The artil skill, allowed commands, linked secrets, and plugins from
    `artil plugin install` stay. The agent's remote Hermes webhook stays
    configured.

    Logout revokes a browser sign-in on the server. A `--token` login is only
    forgotten on this computer, and commands keep signing in with `ARTIL_TOKEN`
    until you unset it; revoke the token on the agent's **Tokens** tab to end
    its access. Copied secrets stay valid.

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

    Credentials are stored with private file permissions in
    `~/.config/artil/credentials.json`, or in `$ARTIL_CONFIG_HOME` or
    `$XDG_CONFIG_HOME/artil` when set. 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.