Skip to main content
@devtune/cli provides the devtune executable for Node 20+. It uses the TypeScript client 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.

​
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 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

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.
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:
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. 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.