> ## Documentation Index > Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Read project measurements, Actions and briefs, launch an explicitly approved managed-agent task, and wait for an existing task. `@devtune/cli` provides the `devtune` executable for Node 20+. It uses the [TypeScript client](/sdk/typescript) for every API call. Installation from npm follows release of both the CLI and its SDK dependency. This work has not published either package. The installation command applies after release. ```sh theme={null} npm install -g @devtune/cli devtune --help devtune --version devtune instructions ``` ## Project configuration Create a project API key in **API Keys** in the account sidebar. Set `DEVTUNE_API_KEY` and `DEVTUNE_PROJECT_ID` in your process environment. The key must belong to that project. `--project UUID` overrides the project ID. See [authentication](/api-reference/authentication) for API access and scopes. The CLI stores no secrets and offers no API-key argument or login discovery. Help, version and the packaged workflow instructions work offline without a key. Use `DEVTUNE_API_BASE_URL` or `--base-url URL` for an explicit API root, including `/api/v2`. The default is `https://devtune.ai/api/v2`. ## Measurements and Actions ```sh theme={null} devtune status --json devtune summary citations --window 30 --json devtune summary traffic --window 90 --json devtune summary results --window 90 --page-size 25 --json devtune actions list --page 1 --page-size 25 --json devtune actions get ACTION_UUID --max-pages 10 --page-size 25 --json devtune actions brief ACTION_UUID --json devtune actions draft ACTION_UUID --json ``` Status reads citation and AI Traffic summaries. These reads support 30 or 90 day windows, defaulting to 30. Results supports 7, 30, 90 or 365 days. Use returned window dates. Null citation stats with unavailable coverage mean no measurement, not a measured zero. AI Traffic includes project-wide sensor state. A healthy quiet sensor is `no_recent_traffic`; `inactive` needs attention. Snippet coverage does not establish server-side answer fetch or 404 coverage. Results reports observed before/after movement, not causation. Preserve null deltas, evidence quality, `unmeasured` and `still_measuring`. Use `--intervention UUID` for an existing measurement's impact windows. Actions list returns one page with bounded evidence context. Page starts at 1; page size is 1 through 100 and defaults to 25. Continue with returned `pagination.totalPages`. Results uses `pagination.hasMore` and `pagination.nextCursor`, supplied through `--cursor` with other filters unchanged. Bound your loops and report incomplete results. The CLI does not fetch every page silently. `actions get ACTION_UUID` searches the current project's Actions workspace using SDK list pages and evidence context. Defaults are `--start-page 1`, `--max-pages 10` and `--page-size 25`. Max pages accepts 1 through 100; start page accepts 1 through 1000000. The lookup sends no status filter and includes the workspace's workflow statuses. Rows without a workflow state are outside this population; this is not a search of every historical record or another project. Lookup JSON is `{action, pages, lookup}`. The matching row retains workflow status, opportunity, evidence and nulls. Every full list envelope is retained in `pages`. A complete search from page 1 with no match returns `lookup.state: "absent"` and exits 7, meaning not observed in the pages read. Live pagination cannot prove current absence. A bound with more pages returns `incomplete`, exits 6 and provides `lookup.nextPage` for `--start-page`. Keep page size unchanged. A search starting later cannot establish absence from earlier pages; reaching the end without a match remains incomplete and points back to page 1. Invalid, overlapping or changing pagination exits 4. Short or empty pages do not establish the end when metadata says more pages remain. Live pagination is not a snapshot; restart if the workspace changes during lookup. Brief and draft commands read existing artifacts by Action ID. They do not generate missing content. Suggestions steer around locked pages and say when they do. Draft content needs human approval before publishing. Scopes are `citations.read` and `traffic.read` for status, `actions.read` for Actions, `outcomes.read` for Results, `agents.read` for waiting and `agents.run` for launching. Existing keys do not automatically gain newly added scopes. ## Approved managed-agent task Launching can spend credits. Obtain explicit human intent for the specific task. Save a UUID with the exact project, agent and instructions before launching. The CLI requires both `--approve-metered` and your saved `--idempotency-key`. ```sh theme={null} devtune agents run --agent AGENT_KEY --instructions 'Approved drafting task' \ --approve-metered --idempotency-key SAVED_UUID --wait --json ``` A launch needs an eligible key creator with project manage permission, available evidence and credits. It sends one POST and never retries automatically. The CLI prints the saved key to stderr before launching, then prints the returned task ID and key before optional waiting. Capture stderr or copy those details into your task record. If a response is lost, the launch may already have been accepted. Keep the same key and inputs. Only replay the same request after an explicit decision to retry. A different UUID may create another charged task. Resume waiting by task ID: ```sh theme={null} devtune agents wait TASK_UUID --deadline-ms 120000 --poll-ms 3000 --json ``` The total wait defaults to two minutes and is bounded at 15 minutes, including reads, retries and sleeps. Poll intervals accept 1 through 60000 ms. SIGINT and SIGTERM cancel the local CLI request. Cancelling the CLI does not cancel server work. Successful terminal states are `draft_ready`, `approved` and `dismissed`; `failed`, `blocked` and server `canceled` are failures. Unknown statuses remain pending until the deadline. No CLI command publishes output. Drafts require human approval. ## JSON and exit codes `--json` reserves stdout for one JSON value, with no banners. Individual reads and launches without waiting return complete API envelopes, except the Action lookup wrapper described above. Status returns `{citations, traffic}` with both envelopes intact. Waiting returns `{run, wait}`; a launch with waiting returns `{launch, run, wait}`. `run` is the last full API envelope or null if no poll completed. Coverage, windows, nulls and pagination are preserved. A reused task that ended unsuccessfully with `--wait` retains the wrapper with `run: null` and `wait: {state: "failed", taskId}`, exits 5 and never polls. Without `--wait`, it returns the raw launch envelope. A dispatch failure during the current request returns an API error and exits 4. Errors and launch recovery messages go to stderr as JSON. | Exit | Meaning | | - | - | | 0 | Successful read, accepted launch or successful terminal wait | | 2 | Usage or local configuration error before transport | | 3 | Authentication or permission error, HTTP 401/403 | | 4 | Other API errors, credits/rate limits, network or protocol error | | 5 | Task failed, blocked or server-canceled, including a reused task | | 6 | Incomplete Action lookup, request timeout, pending deadline or CLI cancellation | | 7 | Action not observed after traversing the live workspace from page 1 | On a failed or pending wait, stdout can still hold the last full task envelope. Read stderr. Resume `agents wait` with its task ID only for pending work. For a terminal failure, inspect the ended task before any new launch. Do not relaunch just to continue waiting. `devtune instructions` prints workflow v1 shipped with the installed CLI release. `devtune instructions --json` includes the CLI version and workflow version for coding agents. It covers configuration, scopes, JSON, pagination, coverage, explicit metered intent and recovery. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.