--- title: "CLI commands" description: "Every lookio command for resources, sites, assistants, questions, conversations, tags, members, account and diagnostics, with its options and what it costs." canonical: "https://lookio.app/docs/cli/commands" updated: "2026-11-01" --- # CLI commands Run `lookio --help` or `lookio --help` for the options of a command. `lookio help --json` prints the whole command tree as one JSON document, which is what an AI agent should read first. It is long: `lookio help --json` (for example `lookio help ask --json`) describes one command alone. Only `lookio ask` spends credits. Every other command is free. ## Account ```bash lookio account lookio credits lookio usage --from 2026-01-01 --to 2026-01-31 --granularity day ``` | Command | What it does | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | The workspace, the plan and its limits, what this credential may do, the query modes with their prices and the file formats Lookio reads. Run it first. | | `credits` | The credit balance and every grant with its expiry. | | `usage` | Answers and credits over a period, 30 days by default, with the breakdown by mode, assistant and origin, and the words stored against your plan. `--granularity` is `day`, `week` or `month`. | ## Resources ```bash lookio resources list --type url --tag pricing --limit 50 lookio resources get RESOURCE_ID lookio resources add-text --title "Refund policy" --from-file policy.md --tags legal,faq lookio resources add-url https://example.com/pricing --title "Pricing" lookio resources add-file ./handbook.pdf --tags hr lookio resources update RESOURCE_ID --title "New title" --tags a,b lookio resources content RESOURCE_ID lookio resources reindex RESOURCE_ID lookio resources delete RESOURCE_ID --force ``` | Command | What it does | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resources list` | Newest first. Filter with `--type` (`text`, `file`, `url`, `site`), `--tag`, `--status` (for example `failed`) and `--query`, a search in the title. `--limit` is 1 to 100, and `--cursor` takes the `next_cursor` of the previous page. | | `resources get ` | One resource and its status. Poll it after an import. | | `resources add-text` | Add a text, with `--text`, or `--from-file` (use `-` for standard input). Up to 100,000 characters. | | `resources add-url ` | Add one public web page. | | `resources add-file ` | Upload a file, streamed from disk. | | `resources update ` | Change `--title`, `--tags` (replaces the list, an empty value clears it), `--text` for a text resource, or `--source`. | | `resources content ` | The text as indexed, and what could not be read. A long text comes in pieces: continue with `--offset` set to the `next_offset` of the previous call, and set the piece size with `--limit`. | | `resources reindex ` | Read it again. | | `resources delete ` | Delete it. Asks to confirm, or needs `--force`. | `add-text`, `add-url`, `add-file` and `sites add` also take `--tags a,b` and `--source`, the text shown with every citation of the resource. ## Sites ```bash lookio sites preview https://example.com/docs lookio sites add https://example.com --include "/docs/**" --exclude "/blog/**" --schedule every_3_days lookio sites pages RESOURCE_ID lookio sites rules RESOURCE_ID --include "/docs/**" lookio sites retry RESOURCE_ID ``` | Command | What it does | | --------------------- | ----------------------------------------------------------------------------------- | | `sites preview ` | Finds the pages without creating anything, so you can try rules first. | | `sites add ` | Imports a site as one resource. | | `sites pages ` | Every page with its state, and why one failed. | | `sites rules ` | Replaces all the rules, then syncs. Omit `--schedule` to keep the current interval. | | `sites retry ` | Reads the failed pages again. | The rule options are repeatable: `--include`, `--exclude` and `--exclude-url`. You can also pass `--regex` and `--schedule manual|daily|weekly|monthly|every_N_days|every_N_weeks|every_N_months`. Omit `--schedule` when adding a site to use the plan default: manual on Free, weekly on paid plans. Recurring schedules require a paid plan and range from 1-90 days, 1-52 weeks or 1-12 months. See [Websites](/docs/platform/websites#keep-it-in-sync). ## Assistants ```bash lookio assistants list lookio assistants get ASSISTANT_ID lookio assistants create --name "Support" --context "You are the help center assistant of Acme, talking to customers" --resources ID1,ID2 lookio assistants create --name "Pricing bot" --follow-tags pricing lookio assistants update ASSISTANT_ID --knowledge all lookio assistants delete ASSISTANT_ID --force ``` Deleting an assistant needs the `assistants:delete` scope, and is refused while a [widget](/docs/widget/overview) uses it. `create` and `update` take `--name`, `--context`, `--output-guidelines`, `--resources `, `--follow-tags ` and `--knowledge all|selected|tags`. Lists you pass replace the previous lists. Without `--knowledge`, `create` infers it from the lists. `update` changes only the options you pass. ## Asking questions ```bash lookio ask ASSISTANT_ID "What is the refund window?" lookio ask ASSISTANT_ID "And for annual plans?" --conversation CONVERSATION_ID lookio ask ASSISTANT_ID "What is the refund window?" --end-user user_42 lookio ask ASSISTANT_ID "A private question" --no-store lookio ask ASSISTANT_ID "Summarise the handbook" --mode deep --stream lookio ask ASSISTANT_ID "And for annual plans?" --history-file turns.json ``` | Option | Effect | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--mode flash\|eco\|deep` | The query mode. Flash is the default. | | `--conversation ` | Continue a conversation: the `conversation_id` of an earlier answer. Send only the new question, the history is read server-side. Exclusive with `--history-file` and `--no-store`. | | `--end-user ` | API keys only. Your own id for the person asking, 1 to 200 characters of letters, digits and `. _ @ : + -`. It groups that person's conversations, and the conversation can then only be continued with the same `--end-user`. | | `--no-store` | API keys only. Keep nothing: no conversation and no log, and the ids come back null. Otherwise the exchange is kept 90 days and shows in the [logs](/docs/platform/logs). | | `--history-file ` | Only if you keep the conversation yourself: the previous turns as a JSON array of `{"role": "user" or "assistant", "content": "..."}`, oldest first, or `-` for standard input. The last 6 are used. Prefer `--conversation`. | | `--stream` | Show the answer as it is written. In a terminal, text then sources. Otherwise one JSON object per line, one per event. | A non-streamed answer prints `answer`, `citations`, `credit_cost`, `credits_remaining`, and the `conversation_id` and the answer's `message_id` to continue it and rate it (null with `--no-store`). See [Conversations and end users](/docs/platform/conversations-and-end-users). In JSON mode, a streamed answer looks like this: ```text {"event":"status","data":{"phase":"searching"}} {"event":"delta","data":{"text":"The refund window is "}} {"event":"done","data":{"answer":"...","citations":[],"conversation_id":"CONVERSATION_ID","message_id":"MESSAGE_ID","credit_cost":30,"credits_remaining":970,"simulated":false}} ``` An `error` event ends the command with a failure, and out of credits ends it with exit code `7`. See [Streaming](/docs/api/streaming) and [Exit codes](/docs/cli/exit-codes). ## Conversations ```bash lookio conversations list --assistant ASSISTANT_ID --end-user user_42 --limit 50 lookio conversations get CONVERSATION_ID lookio conversations rename CONVERSATION_ID "Refund questions" lookio conversations delete CONVERSATION_ID --force lookio conversations feedback CONVERSATION_ID MESSAGE_ID down --comment "Out of date" ``` | Command | What it does | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `conversations list` | Your conversations, latest activity first. Filter with `--assistant` and, for an API key, `--end-user`, and page with `--limit` and `--cursor`. Each row has a `channel`: `personal`, `api` or `mcp`. | | `conversations get ` | One conversation with its messages, citations, answer ids and thumbs. | | `conversations rename ` | Changes the title, 1 to 100 characters. Free. | | `conversations delete <id>` | Deletes the conversation and its messages. Asks to confirm, or needs `--force`. An API key's conversation also leaves the logs. | | `conversations feedback <id> <message_id> <up\|down\|none>` | Records your user's thumb on an answer of an API key's conversation, with `--comment`. `none` takes it back. Free. | After `lookio auth login` these are your own chats, personal. With an API key they are the conversations it started, and `--end-user` on `get`, `rename`, `delete` and `feedback` makes a conversation of another end user answer not found. `feedback` works for API keys only: with a login it fails with `feature_not_available` (exit code `3`). See [Conversations and end users](/docs/platform/conversations-and-end-users) and [Feedback on answers](/docs/platform/answer-feedback). ## Logs ```bash lookio logs conversations --rating down --channel widget,api --from 2026-10-01 lookio logs conversations --stats --widget WIDGET_ID lookio logs get CONVERSATION_ID lookio logs answers --result no_answer --channel widget,api lookio logs answers --stats --from 2026-10-01 lookio logs indexing --status failed --resource RESOURCE_ID lookio logs indexing --stats lookio logs activity --origin cli,mcp --target-type assistant --from 2026-10-01 ``` The workspace's four logs. All commands are free. See [Logs](/docs/platform/logs) for what each one holds and how long it is kept. | Command | Scope | What it does | | -------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `logs conversations` | `assistants:write` | What people outside the workspace asked, latest activity first, with who asked, through what, the messages, the credits and the thumbs. A member's own chats are not here. For a person, it needs the right to edit assistants. With `--stats`: conversations, questions, people, credits, thumbs and conversations per channel. | | `logs get <id>` | `assistants:write` | One conversation in full: messages, sources, mode, cost, duration, thumbs and comments. | | `logs answers` | `usage:read` | Every answer from any channel, latest first, with the assistant, who asked, mode, credits, duration, whether the resources held an answer and the conversation when it was kept. No question or answer text. With `--stats`: answers, answered and not, credits, average time and answers per channel. | | `logs indexing` | `resources:read` | Every file, page or text read and indexed, latest first, with its status, words, passages, time and the error of a failure. With `--stats`: indexings, indexed, failed, in progress, unchanged and words indexed. | | `logs activity` | `admin` | Who changed what, through which door, latest first. Admins only, with `lookio auth login`: an API key cannot read it. No `--stats`. | `logs list` and `logs stats` are now `logs conversations` and `logs conversations --stats`. Every list pages with `--limit` and `--cursor`, and prints `More results: add --cursor …` when there is another page. The cursors of `answers`, `indexing` and `activity` are opaque: pass them back unchanged. `--stats` prints the figures instead of the list, over the same filters, and ignores `--limit` and `--cursor`. `--from` and `--to` take an ISO 8601 date or timestamp. A value that is not allowed for `--channel`, `--rating`, `--result`, `--status`, `--source-type`, `--origin` or `--target-type` is refused before any request, with exit code `2`. `conversations` filters: | Option | Keeps | | ------------------------------ | ------------------------------------------------------------- | | `--channel <a,b>` | Only these channels, comma-separated: `widget`, `api`, `mcp`. | | `--widget <id>` | One widget's visitors. | | `--api-key <id>` | Conversations asked with one API key. | | `--assistant <id>` | Conversations with one assistant. | | `--rating <rating>` | `down`, `up`, `rated` or `unrated`. | | `--end-user <id>` | One person. | | `--query <text>` | Words in the title or in any question or answer. | | `--from <date>`, `--to <date>` | Activity since a date, and conversations started before one. | `answers` filters: | Option | Keeps | | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | | `--channel <a,b>` | Only these channels, comma-separated: `chat`, `lookio_ai`, `api`, `mcp`, `widget`. | | `--assistant <id>`, `--widget <id>`, `--api-key <id>` | One assistant, one widget or one API key. | | `--member <id>` | One member's answers (admins). | | `--result <result>` | `answered`, or `no_answer` for the questions the resources could not answer. | | `--mode <mode>` | One query mode. | | `--from <date>`, `--to <date>` | A period. | `indexing` filters: | Option | Keeps | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `--resource <id>` | One resource's indexings. For a site, all its pages. | | `--status <a,b>` | Only these statuses, comma-separated: `queued`, `processing`, `indexed`, `replaced`, `unchanged`, `skipped`, `failed`. | | `--source-type <type>` | `file`, `url`, `site` or `text`. | | `--query <text>` | Words in the resource's title, the file's name, or the page's address or title. | | `--include-unchanged` | Also the pages a sync re-read and found unchanged. They are left out by default. | | `--from <date>`, `--to <date>` | Indexings started in a period. | `activity` filters: | Option | Keeps | | ------------------------------ | ------------------------------------------------------------------------------------------- | | `--actor <id>` | What one member (user id) or API key (key id) did. | | `--origin <a,b>` | Only these doors, comma-separated: `app`, `api`, `cli`, `mcp`, `agent`, `system`. | | `--target-type <type>` | `resource`, `assistant`, `widget`, `tag` or `member`. | | `--target <id>` | One resource, assistant, widget or member. | | `--action <action>` | An exact action such as `assistant.updated`, or every action on a kind such as `assistant`. | | `--query <text>` | Words in the name of what changed. | | `--from <date>`, `--to <date>` | A period. | ## Widgets ```bash lookio widgets list lookio widgets create --assistant ASSISTANT_ID --domain docs.acme.com --mode flash lookio widgets update WIDGET_ID --status paused lookio widgets update WIDGET_ID --setting accent=#0b5fff --setting sources=numbered_no_links lookio widgets update WIDGET_ID --monthly-credits 5000 --limit-per-visitor-hour 30 lookio widgets duplicate WIDGET_ID lookio widgets set-image WIDGET_ID launcher ./logo.png lookio widgets set-image WIDGET_ID favicon ./favicon.ico lookio widgets clear-image WIDGET_ID favicon lookio widgets snippet WIDGET_ID --format embed lookio widgets conversations WIDGET_ID lookio widgets conversations WIDGET_ID CONVERSATION_ID lookio widgets delete WIDGET_ID --force ``` A [widget](/docs/widget/overview) shows an assistant to anonymous visitors on a website. Managing widgets is free. Visitors' answers are charged to the workspace in the widget's mode. `duplicate` copies a widget under a new id, with its images, and counts against the plan's widget limit. `set-image` takes `launcher` or `favicon` and a PNG, JPEG, WebP or GIF file (ICO too for the favicon) up to 256 KB, on paid plans. | Command | What it does | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `widgets list` | Widgets, newest first, with this month's conversations, answers and credits. | | `widgets get <id>` | One widget with its settings, limits, numbers and install snippets. | | `widgets create` | Creates a widget. Needs `--assistant`. `--name` is optional. | | `widgets update <id>` | Changes only what you pass. | | `widgets snippet <id>` | Prints one install snippet as plain text. `--format` is `bubble` (the default), `embed`, `hosted` or `iframe`. The `iframe` snippet belongs to the `embed` format. In JSON it prints `format` and `snippet`. | | `widgets conversations <id> [conversation_id]` | Without a conversation id, lists what visitors asked, latest first (`--limit`, `--cursor`): the same as `logs conversations --widget <id>`. With one, shows that conversation with its costs, thumbs and comments. | | `widgets delete <id>` | Deletes the widget and its visitors' conversations. Asks to confirm, or needs `--force`. | `create` and `update` share these options: | Option | Effect | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--mode <mode>` | The query mode of every answer, so its price: `flash` (the default), `eco` or `deep`. | | `--status <status>` | `live` answers visitors. `paused` shows nothing and answers nothing. | | `--domain <host>` | A website allowed to show the widget, such as `docs.acme.com` or `*.acme.com`. Repeat it or separate hosts with commas. On `update` it replaces the whole list, and `--domain ''` clears it. | | `--setting <key=value>` | Sets one appearance or words field and keeps the others. Repeatable. The keys are `theme`, `accent`, `radius`, `position`, `launcher`, `launcher_label`, `title`, `greeting`, `placeholder`, `suggestions`, `disclaimer`, `language`, `sources`, `memory`, `visitor_history`, `feedback`, `branding`, `bubble`, `embed` and `hosted_page`. The last three turn the chat bubble (on by default), the in-page chat (off) and the hosted page (off) on or off. | | `--limit-per-visitor-hour <n>` | Questions one visitor may ask per hour, 1 to 500. | | `--limit-per-visitor-day <n>` | Questions one visitor may ask per day, 1 to 2,000. | | `--monthly-credits <n or none>` | Credits the widget may spend per month, 10 to 10,000,000, or `none` for no ceiling. | The allowed domains and the `sources` values are explained in [Access and limits](/docs/widget/access-and-limits) and [Appearance](/docs/widget/appearance#sources). ## Tags ```bash lookio tags list lookio tags rename old-name new-name lookio tags delete old-name --force ``` `rename` and `delete` are for workspace admins signed in with `lookio auth login`. ## Members ```bash lookio members list lookio members set USER_ID --allow resources_create,api --deny mcp --assistants all ``` `members set` needs `--assistants`, a comma-separated list of ids or `all`, and it always replaces the member's current list. `--allow` and `--deny` name permissions: `resources_list`, `resources_create`, `resources_edit`, `resources_delete`, `assistants_create`, `assistants_edit`, `assistants_delete`, `api` and `mcp`. The older spellings `resourcesCreate` and `resources-create` are still accepted. Paid plans only. See [Members and permissions](/docs/platform/members-and-permissions). ## Escape hatch ```bash lookio api GET "/resources?type=url&limit=50" lookio api POST /tags/rename --data '{"from":"old","to":"new"}' ``` `lookio api <method> <path>` makes an authenticated request to any endpoint, with the same retries and the same error format. The path may start with `/v1` or not, and may carry a query string. `--data` takes inline JSON, `@file` or `-` for standard input, and `--header "Name: value"` adds a header. The response is printed as the API returned it, envelope included. ## Diagnostics and help | Command | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `doctor` | Checks the connection, the credential, the CLI version and the clock, and exits non-zero on failure. | | `feedback send` | Sends feedback about the API, CLI or MCP. Needs `--problem`, `--situation` and `--expected-solution`. | | `mcp` | Runs a stdio bridge to the MCP server, for clients that can only launch a process. See [Connect an AI client](/docs/mcp/connect#clients-that-need-a-local-process). | | `completion <shell>` | Prints a completion script for `bash`, `zsh` or `fish`. | | `help --json` | The full command surface, the exit codes and the error format as JSON. | | `help <command> --json` | One command (and its subcommands) as JSON. |