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

# Quickstart

> Install the Trilo CLI and run your first commands in under 2 minutes

Get the Trilo CLI running on your machine in under 2 minutes.

## Prerequisites

You need [Bun](https://bun.sh) installed (v1.2+):

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

## Setup

<Steps>
  <Step title="Install the CLI">
    From the Trilo monorepo:

    ```bash theme={null}
    cd packages/cli && bun link
    ```

    This makes the `trilo` command available globally.

    Verify it works:

    ```bash theme={null}
    trilo --version
    ```
  </Step>

  <Step title="Log in">
    ```bash theme={null}
    trilo login
    ```

    Your browser opens to authorize the CLI. Click **Authorize** and you're done — the token is stored securely and refreshes automatically.

    <Tip>
      For CI/CD or scripting, use a [Personal Access Token](/developers/cli/authentication#personal-access-tokens-pat) instead.
    </Tip>
  </Step>

  <Step title="Try it out">
    ```bash theme={null}
    # List your projects
    trilo projects list

    # List tasks in a project
    trilo tasks list --limit 5

    # Get JSON output for scripting
    trilo tasks list --limit 100 --json | jq '.data | length'
    ```
  </Step>

  <Step title="Install shell completions">
    Tab completion for all commands and flags:

    ```bash theme={null}
    trilo completions install
    ```

    Restart your shell, then try `trilo tasks <tab>` to see completions.
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/cli/authentication">
    OAuth login, PAT tokens, CI/CD setup, and environment variables.
  </Card>

  <Card title="Commands Reference" icon="terminal" href="/developers/cli/commands">
    All 19 commands with examples and scripting patterns.
  </Card>
</CardGroup>

## Common Workflows

### Quick task check

```bash theme={null}
trilo tasks list --status in_progress
```

### Create a task from terminal

```bash theme={null}
trilo tasks create --title "Fix login bug" --project-id <id> --priority high
```

### Pipe JSON to other tools

```bash theme={null}
# Export project list as CSV
trilo projects list --json | jq -r '.data[] | [.name, .id] | @csv'

# Count blocked tasks
trilo tasks list --status blocked --json | jq '.data | length'
```

### Trigger a workflow

```bash theme={null}
trilo workflows run --page-id <workflow-page-id>
trilo workflows status --page-id <workflow-page-id>
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="trilo login fails with 'Port 9876 is already in use'">
    The CLI needs port 9876 for the OAuth callback. Check what's using it:

    ```bash theme={null}
    lsof -i :9876
    ```

    Kill the process or wait for it to finish, then retry `trilo login`.
  </Accordion>

  <Accordion title="'Authentication failed. Run: trilo login'">
    Your token may have expired and refresh failed. Run `trilo login` again to get a fresh token.

    If using a PAT, check that `TRILO_TOKEN` is set correctly and the token hasn't been revoked.
  </Accordion>

  <Accordion title="Commands return empty results">
    Make sure you have the right workspace selected:

    ```bash theme={null}
    trilo workspace current
    trilo workspace list
    trilo workspace set <correct-workspace-id>
    ```
  </Accordion>

  <Accordion title="'Could not connect' errors">
    Check that you can reach the API:

    ```bash theme={null}
    curl -s https://api.trilo.chat/health
    ```

    If using a custom API URL, verify `TRILO_API_URL` is correct.
  </Accordion>
</AccordionGroup>