> For the complete documentation index, see [llms.txt](https://www.quillaudits.com/quillshield/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.quillaudits.com/quillshield/developers/cli-submit-and-watch.md).

# CLI: submit & watch

Submit audits, pay, and stream progress with qs.

`qs audit` prepares the project, creates a **draft quote**, then (unless `--no-pay`) charges and starts the job — the same sequence as web Checkout.

There is **no** free start path. `POST /v1/audit/submit` returns `402 payment_required`; the CLI treats that as the handoff into checkout. The quote uses **QS-PAYG-USD-V6**.

## Submit

```bash
# Git (mock or live payment)
qs audit https://github.com/org/contract --ref main --yes --watch

# Local folder
qs audit --dir ./contracts --yes --watch

# Zip / single .sol
qs audit --zip ./project.zip --name "My Project" --yes

# Prepare only (stop after quote)
qs audit --dir ./contracts --no-pay
qs pay <quote-id> --yes --watch
```

{% hint style="warning" %}
Always pass **`--yes`** in CI. Without it, a non-interactive run refuses to charge.
{% endhint %}

## Options

| Flag                      | Meaning                                          |
| ------------------------- | ------------------------------------------------ |
| `--ref`                   | Git branch/tag/commit                            |
| `--name`                  | Project name override                            |
| `--scope a.sol,b.sol`     | Explicit scope (default: all `.sol`)             |
| `--coupon CODE`           | Apply coupon before order                        |
| `--method stripe\|crypto` | Payment method (default `stripe`)                |
| `--yes`                   | Skip interactive charge confirm (required in CI) |
| `--no-pay`                | Create project + quote only                      |
| `--no-open` / `--open`    | Browser control for live Stripe Checkout         |
| `--watch`                 | Stream progress after the job starts             |

## Payment modes

* **Mock Stripe** (`GET /v1/config` → `stripe_mock: true`): the CLI confirms with `POST /v1/orders/:id/confirm-stripe-payment`. No browser. Retired routes such as `POST /v1/webhooks/mock-confirm` reject.
* **Live Stripe**: prints the Checkout URL, opens a browser when a TTY is present (unless `--no-open`), polls until paid, then starts the audit.
* **$0 due** (coupon / wallet credits, including a reused identical report): order is auto-paid; audit starts immediately.

{% hint style="info" %}
**Workflows.** `qs audit` has no Workflow step. A new snapshot runs your organization's default workflow (the QuillShield Audit Agent unless an admin changed it) on QuillShield AI, with the default answers to its questions. A snapshot that already has a workflow saved in the dashboard runs that one; if it runs on a Claude or ChatGPT plan, pay for it in the dashboard instead. See [API: workflows](https://www.quillaudits.com/quillshield/developers/api-workflows.md).
{% endhint %}

## Track progress

```bash
qs status <job-id>
qs watch <job-id>     # SSE with poll fallback
qs cancel <job-id>
```

## Results

```bash
qs findings <job-id>
qs report <job-id> --format pdf --out ./report.pdf
qs projects
qs versions <project-id>
```

`--format` accepts `pdf`, `json`, or `md`.

See quotes, pay & wallet for paying a quote later, top-ups, and orders.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.quillaudits.com/quillshield/developers/cli-submit-and-watch.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
