# Quickstart

> Initialize `~/.ati/`, import a no-auth OpenAPI provider, store a key, run `ati tool list` and `ati run`, and verify success with `ati tool info`.

- Repository: Parcha-ai/ati
- GitHub: https://github.com/Parcha-ai/ati
- Human docs: https://grok-wiki.com/public/docs/parcha-ai-ati-a9d4398f11fa
- Complete Markdown: https://grok-wiki.com/public/docs/parcha-ai-ati-a9d4398f11fa/llms-full.txt

## Source Files

- `README.md`
- `src/cli/init.rs`
- `src/cli/call.rs`
- `manifests/clinicaltrials.toml`
- `specs/clinicaltrials.json`
- `src/cli/tools.rs`

---

---
title: "Quickstart"
description: "Initialize `~/.ati/`, import a no-auth OpenAPI provider, store a key, run `ati tool list` and `ati run`, and verify success with `ati tool info`."
---

Local mode loads provider manifests from `~/.ati/manifests/`, resolves OpenAPI tools from `~/.ati/specs/`, and executes HTTP calls through `ati run` without proxy credentials when `ATI_PROXY_URL` is unset.

## Prerequisites

Install the `ati` binary (release tarball, `cargo install agent-tools-interface`, or a local `cargo build --release`). You need outbound HTTPS to fetch an OpenAPI spec URL.

<CardGroup>
  <Card title="Installation" href="/installation">
    Pre-built musl binaries, crates.io install, and platform notes.
  </Card>
</CardGroup>

## What gets created

`ati init` and first-use auto-setup both target the same directory. Resolution order is `ATI_DIR` → `$HOME/.ati` → `.ati`.

| Path | Role |
|------|------|
| `~/.ati/manifests/` | Provider TOML files (`[provider]`, optional `[[tools]]`) |
| `~/.ati/specs/` | OpenAPI JSON referenced by `openapi_spec` |
| `~/.ati/skills/` | Installed skill directories |
| `~/.ati/config.toml` | Optional proxy/JWT settings |
| `~/.ati/credentials` | Dev-mode plaintext keys (`ati key set`) |

<Note>
Every command calls `ensure_ati_dir()` before running, which creates `manifests/`, `specs/`, `skills/`, and a stub `config.toml` if missing. `ati init` is still the explicit way to lay out the tree and print next-step hints.
</Note>

:::files
~/.ati/
├── config.toml
├── manifests/
│   └── clinicaltrials.toml    # after import-openapi
├── specs/
│   └── clinicaltrials.json    # downloaded/normalized spec
├── skills/
└── credentials                # after ati key set (optional for no-auth)
:::

## End-to-end flow

```mermaid
sequenceDiagram
  participant You
  participant CLI as ati CLI
  participant Dir as ~/.ati/
  participant API as clinicaltrials.gov

  You->>CLI: ati init
  CLI->>Dir: manifests/, specs/, skills/, config.toml
  You->>CLI: ati provider import-openapi URL
  CLI->>API: GET openapi.json
  API-->>CLI: OpenAPI 3.0 spec
  CLI->>Dir: specs/clinicaltrials.json
  CLI->>Dir: manifests/clinicaltrials.toml
  You->>CLI: ati tool list --provider clinicaltrials
  CLI->>Dir: load manifest + register OpenAPI tools
  You->>CLI: ati run clinicaltrials:searchStudies ...
  CLI->>API: GET /studies
  API-->>CLI: JSON studies
  You->>CLI: ati tool info clinicaltrials:searchStudies
  CLI-->>You: schema, endpoint, usage line
```

<Steps>
  <Step title="Initialize the ATI directory">
    ```bash
    ati init
    ```

    Creates `manifests/`, `specs/`, and `skills/` under `~/.ati/`, and writes `config.toml` when it does not exist. Use `ati init --proxy` only when you are preparing a JWT-backed proxy host (not required for this local quickstart).

    Verify:

    ```bash
    ls ~/.ati/manifests ~/.ati/specs ~/.ati/skills
    ```
  </Step>

  <Step title="Import a no-auth OpenAPI provider">
    ClinicalTrials.gov publishes a public OpenAPI spec with no API key. ATI derives the provider name `clinicaltrials` from the host `clinicaltrials.gov`.

    ```bash
    ati provider import-openapi https://clinicaltrials.gov/api/v2/openapi.json
    ```

    The command downloads the spec (30s timeout, SSRF checks on the URL), detects `auth_type = "none"`, writes `~/.ati/specs/clinicaltrials.json`, and generates `~/.ati/manifests/clinicaltrials.toml` with `handler = "openapi"`. OpenAPI operations register at load time as tools named `clinicaltrials:<operationId>` (for example `clinicaltrials:searchStudies`).

    Preview without writing files:

    ```bash
    ati provider import-openapi https://clinicaltrials.gov/api/v2/openapi.json --dry-run
    ```

    Override the derived name:

    ```bash
    ati provider import-openapi https://clinicaltrials.gov/api/v2/openapi.json --name clinicaltrials
    ```
  </Step>

  <Step title="Store a credential (dev mode)">
    No-auth providers do not read a keyring entry on `ati run`, but storing a key exercises the dev credential path used by authenticated providers.

    ```bash
    ati key set finnhub_api_key "your-key-here"
    ati key list
    ```

    Keys persist in `~/.ati/credentials` as JSON with file mode `0600`. `ati key list` prints masked values. When you later import an API that sets `auth_key_name` in its manifest, ATI resolves that name from the same store (or from `keyring.enc` in local/proxy hardened setups).

    <Tip>
    For the ClinicalTrials.gov step alone, skip `ati key set` — `auth_type = "none"` omits `auth_key_name` from the generated manifest.
    </Tip>
  </Step>

  <Step title="List tools">
    ```bash
    ati tool list --provider clinicaltrials
    ```

    Registry load reads `~/.ati/manifests/*.toml`, loads the spec from `~/.ati/specs/`, and registers each OpenAPI operation. Table output is the default when you pass `--output table`; the CLI global default is `json` unless you set `ATI_OUTPUT`.

    ```bash
    ATI_OUTPUT=table ati tool list --provider clinicaltrials | head -5
    ```

    Expect rows with columns `PROVIDER`, `TOOL`, and `DESCRIPTION`, where `TOOL` values look like `clinicaltrials:searchStudies`.
  </Step>

  <Step title="Run a tool">
    Query parameters from the spec are passed as `--query.term`, `--pageSize`, and similar flags. ATI classifies them using `x-ati-param-location` metadata injected during OpenAPI import.

    ```bash
    ati --output text run clinicaltrials:searchStudies --query.term "cancer" --pageSize 3
    ```

    With `ATI_PROXY_URL` unset, `ati run` loads manifests and credentials locally, classifies arguments, and issues `GET https://clinicaltrials.gov/api/v2/studies` with the query string built from your flags.

    <RequestExample>
    ```bash
    ati --output json run clinicaltrials:searchStudies --query.term "cancer" --pageSize 3
    ```
    </RequestExample>

    <ResponseExample>
    ```json
    {
      "studies": [ "... trial records ..." ],
      "nextPageToken": "..."
    }
    ```
    </ResponseExample>
  </Step>

  <Step title="Verify with tool info">
    ```bash
    ati --output text tool info clinicaltrials:searchStudies
    ```

    Confirms the namespaced tool name, provider description, `handler: openapi`, resolved HTTP endpoint, input schema properties (`query.term`, `pageSize`, filters), and a generated usage line.

    ```bash
    ati --output json tool info clinicaltrials:searchStudies
    ```

    Returns structured fields: `name`, `provider`, `method`, `endpoint`, `input_schema`, `skills`.
  </Step>
</Steps>

## Command reference (this walkthrough)

| Command | Purpose |
|---------|---------|
| `ati init` | Create `~/.ati/` layout and default `config.toml` |
| `ati provider import-openapi <url>` | Download spec, write manifest + spec, register tools |
| `ati key set <name> <value>` | Store dev credential in `~/.ati/credentials` |
| `ati key list` | List key names with masked values |
| `ati tool list [--provider NAME]` | Scope-filtered catalog of public tools |
| `ati run <provider>:<tool> --arg value` | Execute one tool call |
| `ati tool info <provider>:<tool>` | Schema, endpoint, and example usage |

## Generated manifest shape

After import, `~/.ati/manifests/clinicaltrials.toml` matches the curated repo manifest: OpenAPI handler, no auth, spec file reference.

```toml
[provider]
name = "clinicaltrials"
description = "ClinicalTrials.gov — Search the US clinical trials database"
handler = "openapi"
base_url = "https://clinicaltrials.gov/api/v2"
openapi_spec = "clinicaltrials.json"
auth_type = "none"
category = "medical"
```

Tools are not listed in TOML; they are materialized from `clinicaltrials.json` at registry load time.

## Troubleshooting

| Symptom | Likely cause | What to do |
|---------|----------------|------------|
| `no tools available` on `ati tool list` | Empty `~/.ati/manifests/` or scope restriction | Run `import-openapi` or check `ATI_SESSION_TOKEN` scopes when JWT validation is enabled locally |
| `Unknown tool: 'clinicaltrials:searchStudies'` | Manifest/spec missing or load error | Confirm `~/.ati/manifests/clinicaltrials.toml` and `~/.ati/specs/clinicaltrials.json` exist; re-run import |
| Import URL fails with SSRF message | Private/redirect URL blocked | Use the public HTTPS spec URL directly |
| `ATI_SESSION_TOKEN is required` | JWT validation configured without a token | Unset JWT env vars for unrestricted dev mode, or issue a token with `ati token issue` |
| Empty or error HTTP response on `ati run` | Network or upstream API issue | Retry with `--verbose`; confirm parameters via `ati tool info` |

<Warning>
When `ATI_JWT_PUBLIC_KEY`, `ATI_JWT_SECRET`, or proxy JWT settings in `config.toml` are active, local commands require a valid `ATI_SESSION_TOKEN`. Without JWT configuration, local mode stays unrestricted for development.
</Warning>

## Related pages

<CardGroup>
  <Card title="Overview" href="/overview">
    Execution surfaces, provider catalog, and proxy vs local routing.
  </Card>
  <Card title="Import OpenAPI providers" href="/import-openapi">
    Tag filters, operation caps, `inspect-openapi`, and auth detection.
  </Card>
  <Card title="Execution modes" href="/execution-modes">
    Dev credentials, encrypted keyring, and `ATI_PROXY_URL` proxy mode.
  </Card>
  <Card title="Configure JWT and keys" href="/configure-jwt-and-keys">
    `ati key`, `ati token`, and scoped session tokens.
  </Card>
  <Card title="Scopes and tool discovery" href="/scopes-and-tool-discovery">
    `ati tool search`, scope-filtered listing, and `ati assist`.
  </Card>
  <Card title="OpenAPI stock research workflow" href="/openapi-stock-research">
    Finnhub import, key setup, and chained quote calls.
  </Card>
</CardGroup>