--- 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/developers/cli/commands" updated: "2026-11-08" --- # CLI commands `lookio --help` gives the options of a command. `lookio help --json` prints all commands as one JSON document: an AI agent reads it first. `lookio help --json` describes one command. Only `lookio ask` and `lookio search` spend credits. All other commands are 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, the credential's scopes, the query modes and their prices, and the file formats. Run it first. | | `credits` | The credit balance and every grant with its expiry. | | `usage` | Answers and credits over a period (default 30 days), by mode, assistant and origin, and the words stored. `--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` (words in the title). `--limit` is 1 to 100. `--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, empty clears it), `--text` for a text resource, or `--source`. Add `--wait` to return when the new text is indexed. | | `resources content ` | The indexed text, and what Lookio could not read. A long text comes in parts: continue with `--offset` set to the previous `next_offset`. `--limit` sets the part size. | | `resources reindex ` | Read it again. Add `--wait` to wait up to 15 seconds for the result. | | `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. Use it to test rules. | | `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. Add `--wait` to wait up to 15 seconds for the sync. | | `sites retry ` | Reads the failed pages again. Add `--wait` to wait up to 15 seconds for them. | You can repeat `--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`. Without `--schedule`, a new site is manual on Free and weekly on paid plans. Recurring schedules need a paid plan: 1 to 90 days, 1 to 52 weeks or 1 to 12 months. See [Websites](/docs/guides/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/guides/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 for your plan's period and shows in the [logs](/docs/guides/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` and `credits_remaining`. It also prints the `conversation_id` and the answer's `message_id`, which you can use to continue the conversation and rate the answer. Both IDs are null with `--no-store`. See [Conversations and end users](/docs/guides/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/developers/streaming) and [Exit codes](/docs/developers/cli/exit-codes). ### Search passages ```bash lookio search ASSISTANT_ID "credit notes" --limit 5 ``` Returns the passages that best match the question, best first, without an answer, for your own model. **1 credit** per search, whatever it finds. Lookio stores nothing. `--limit` is 1 to 20 (default 8). `--history-file` takes the previous messages, like `ask`. It works with your assistants and with public assistants. ## 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. With an API key, they are the conversations it started. With `--end-user`, `get`, `rename`, `delete` and `feedback` return not found for a conversation of another end user. `feedback` works for API keys only. With a login, it fails with `feature_not_available` (exit code `3`). See [Conversations and end users](/docs/guides/conversations-and-end-users) and [Feedback on answers](/docs/guides/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 four logs of the workspace. All commands are free. See [Logs](/docs/guides/logs). | Command | Scope | What it does | | -------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `logs conversations` | `assistants:write` | What people outside the workspace asked, latest first: who, through what, the messages, the credits and the thumbs. Never a member's own chats. A person 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 every channel, latest first: assistant, who asked, mode, credits, duration, if 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 uses `--limit` and `--cursor`, and prints `More results: add --cursor …` when there is another page. Send the cursors back as they are. `--stats` prints the figures for the same filters, not the list, and ignores `--limit` and `--cursor`. `--from` and `--to` take an ISO 8601 date or timestamp. A value that is not valid for `--channel`, `--rating`, `--result`, `--status`, `--source-type`, `--origin` or `--target-type` fails 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/guides/widget/overview) shows an assistant to anonymous visitors on a website. Managing widgets is free. The workspace pays for visitors' answers, at the widget's mode. `duplicate` copies a widget under a new id, with its images, and counts against the plan's widget limit. On paid plans, `set-image` takes `launcher`, `header` or `favicon` and a PNG, JPEG, WebP or GIF file up to 256 KB, or ICO for the favicon. | 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`, `bubbles`, `position`, `launcher`, `launcher_label`, `launcher_icon`, `launcher_size`, `bar_icon`, `bar_translucent`, `header_icon`, `title`, `subtitle`, `greeting`, `placeholder`, `suggestions`, `disclaimer`, `language`, `sources`, `memory`, `visitor_history`, `feedback`, `branding`, `bubble`, `embed` and `hosted_page`. Booleans are `true` or `false`. `suggestions` is a JSON array or a comma list. `bubble`, `embed` and `hosted_page` turn the three formats 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. | | `--limit-per-minute <n>` | Answers the whole widget may give per minute, all visitors together, 10 to 1,000 (default 60). | | `--monthly-credits-enabled true\|false` | Turns the monthly ceiling off or on and keeps its amount. | | `--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/guides/widget/access-and-limits) and [Appearance](/docs/guides/widget/appearance#sources). ## Public assistants ```bash lookio public list --q vat lookio public get ASSISTANT_ID lookio ask ASSISTANT_ID "Is VAT due on a sale to a German company?" lookio assistants publish ASSISTANT_ID --description "Answers questions on EU VAT for freelancers, from official guidance." lookio assistants publication ASSISTANT_ID lookio assistants unpublish ASSISTANT_ID --force ``` `public list` and `public get` read the directory, for free. Ask a public assistant with `lookio ask` or `lookio search`: your workspace pays. `publish`, `publication` and `unpublish` are for admins and are free. `--description` is 40 to 1,000 characters. See [Public assistants](/docs/guides/public-assistants). ## Accesses ```bash lookio accesses list lookio accesses create --name "Partner integrations" --assistant ASSISTANT_ID="Billing questions" --protection keys --modes flash,deep --monthly-credits 5000 lookio accesses update ACCESS_ID --status paused lookio accesses get ACCESS_ID lookio accesses keys create ACCESS_ID --name "Northfield Partners" --monthly-credits 1000 lookio accesses keys update ACCESS_ID KEY_ID --daily-credits 100 lookio accesses keys revoke ACCESS_ID KEY_ID --force lookio accesses delete ACCESS_ID --force ``` An [access](/docs/guides/accesses) shares assistants with people outside the workspace. These commands are for admins and are free. The workspace pays for the callers' questions. | Option of `create` and `update` | Effect | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--name <name>` | 1 to 120 characters. | | `--assistant <id[=description]>` | An assistant to share, with an optional description for callers (up to 1,000 characters). Repeat it, 1 to 20 times. On `update`, it replaces the whole list. | | `--description <text>` | What callers read about the access (up to 2,000 characters). | | `--protection public\|keys` | `public` (default): anyone with the address. `keys`: every call needs an access key (Pro plan). | | `--status live\|paused` | `paused` refuses every call. | | `--modes <list>` | The query modes callers can use: `eco`, `flash`, `deep` (default `flash`), or `none`. | | `--passages true\|false` | Let callers search passages, at 1 credit (default `false`). | | `--daily-credits <n or none>` | The ceiling per UTC day, 1 to 100,000,000. | | `--monthly-credits <n or none>` | The ceiling per UTC month, 1 to 100,000,000. | `keys create` prints the secret (`ak_live_...`) once. Store it and give it to the client. A key's ceilings apply inside the access's ceilings. ## 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` specify 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. Pro and Custom plans only. See [Members and permissions](/docs/guides/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/developers/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. |