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

# CLI

> Discover, run, wait for, and export SocQ tasks from a terminal.

# CLI

Use the SocQ CLI for terminal workflows, automation, and exporting normalized task results as JSON, JSONL, CSV, or tables.

<Warning>
  The `@socq/cli` package is not yet available on the public npm registry. The commands below document the upcoming package and can be used from the SocQ devtools repository during development.
</Warning>

## Install and authenticate

After the package is published:

```bash theme={"system"}
npm install -g @socq/cli
socq auth login
```

For CI, set `SOCQ_API_KEY` instead of using interactive login. Avoid `--api-key` in normal terminal use because command arguments may remain in shell history or process listings.

## Discover endpoints

```bash theme={"system"}
socq platforms
socq tools youtube
socq describe youtube/comments
```

Use `describe` before building automation so the command uses the current input schema and billing information from the Capability Registry.

## Complete your first collection

```bash theme={"system"}
socq youtube comments \
  --urls "https://www.youtube.com/watch?v=VIDEO_ID" \
  --sort-by newest \
  --wait
```

The dynamic command maps directly to:

```text theme={"system"}
REST:      POST /v1/youtube/comments
Endpoint:  youtube/comments
MCP tool:  socq_youtube_comments
CLI:       socq youtube comments
```

Use the stable generic form when inputs come from a file:

```bash theme={"system"}
socq run youtube comments \
  --input-file request.json \
  --format jsonl \
  --output results.jsonl \
  --wait
```

## Resume without resubmitting

If a command returns before the collection finishes, keep the task ID:

```bash theme={"system"}
socq task get TASK_ID
socq task wait TASK_ID --timeout 180
socq task results TASK_ID --format csv --output results.csv
socq task files TASK_ID
```

Do not submit the original collection again just because a local wait timed out. Resume the existing task.

## Output formats

| Format  | Best for                             |
| ------- | ------------------------------------ |
| `table` | Reading a small result in a terminal |
| `json`  | Structured output and scripts        |
| `jsonl` | Streaming or large exports           |
| `csv`   | Spreadsheets and data analysis       |