CLI installation and command reference

Public npm installation is not available yet. Obtain an approved release tarball from Artie, then install it with Node.js 22 or later:

npm install --global ./artie-cli-VERSION.tgz
artie --help
artie login --origin https://api.artie.ai
artie whoami --json
artie doctor --json

Installation downloads a native credential-store adapter for your operating system. Keep npm optional dependencies enabled. macOS ARM64 is the currently validated platform; Linux and other architectures are not yet validated for end-to-end use. Windows is unsupported.

Login discovers the protected MCP resource and managed authorization server. The production and development origins use PKCE by default for their registered native public CLI clients: browser authorization with a random loopback callback, nonce, state and S256 proof. Other clients retain device flow by default; --flow pkce or --flow device explicitly selects a flow. Device flow requires an advertised endpoint and device-code grant, shows the provider confirmation URL and user code, and keeps the device code private. A client must support the selected flow; passing PKCE does not establish device login. Neither flow falls back to the other. Both delegated flows verify the provider's signed access token, exact MCP audience, client and user-consent identity before storing credentials or reporting login success. A setup-required response supplies the actual workspace enrollment URL. Unenrolled credentials do not authorize business commands.

For custom origins, supply --client-id for your registered public client and explicitly select a supported flow. Native operator credentials are separate from delegated automation.

Access and rotating refresh credentials stay in the OS credential store through the native keyring API. No bearer input through arguments, environment, stdin or dotenv, and no plaintext credential fallback. Your operating system must provide an unlocked, accessible credential store; Windows is unsupported. Profiles contain public configuration only. Pending requests and scenario reports are private files under ~/.config/artie or your chosen report path. They may contain the work you submitted, so keep this directory private.

artie artisans --query research --json
artie artisans --starter-catalog --json
artie search 'approved product notes' --type knowledge --type files --json
artie context read /approved-product-notes.md --kind memory --json
artie context lines /large-entry.md --json
artie context read 'Research procedure' --kind skill --json
artie context read ARTISAN_UUID --kind artisan --json
artie files read FILE_ID --max-chars 24000 --json
artie task read-artifact TASK_UUID ARTIFACT_ID --json
artie task create --artisan ARTISAN_UUID --instructions-file brief.txt --key request-key --wait 120 --json
artie task create --artisan ARTISAN_UUID --instructions-file brief.txt --responsibility-file responsibility.json --schedule 'on the 1st of every month' --time-zone America/Los_Angeles --key monthly-responsibility-key --json
artie task list --scope mine --status needs_you --limit 25 --json
artie task show TASK_UUID --all --json
artie task show TASK_UUID --resolved-files --json
artie task refine TASK_UUID --file full-revised-brief.txt --expected-revision CURRENT_REVISION --key refine-key --json
artie task refine TASK_UUID --file extra-note.txt --append --key append-key --json
artie task input TASK_UUID --kind answer --file answer.txt --run RUN_UUID --expected-revision CURRENT_REVISION --key answer-key --json
artie task watch TASK_UUID --wait 120 --json
artie task pause TASK_UUID --key pause-key --json
artie task resume TASK_UUID --key resume-key --json
artie task cancel TASK_UUID --key cancel-key --json
artie task result TASK_UUID --all --run RUN_UUID --json
artie task runs TASK_UUID --limit 5 --json
artie task run TASK_UUID RUN_UUID --json
artie task evidence TASK_UUID --run RUN_UUID --json
artie usage --json

task show --resolved-files returns the current selected files' IDs, revisions and digests, with upload IDs where the selection used an upload. sources.instructionsRevision and resolvedInputs.messageId identify that current selection; these facts do not describe a historical run. Older clients keep the original response unless they opt in.

Use Artisan IDs when a name is ambiguous. List commands return explicit cursors and bounds; continue with --cursor. Task lists also accept --artisan, --parent, --responsibility, --section, --paused, --failed, --include-subtasks and --include-done. --input-refs-file refs.json supplies the canonical array of selected references on creation, input or refinement. Omission on refinement preserves selection; an explicit empty array removes all selected inputs. --acceptance-file criteria.json supplies an array of acceptance criteria on creation. Append reads the entire current brief and its revision, then submits the combined brief. It never replaces the brief with just the note.

--responsibility-file responsibility.json supplies the existing responsibility fields, for example { "ongoing": true }. MCP delegate_task and the API accept the same responsibility object. --schedule supports a monthly calendar date, such as the 1st, in --time-zone; an absent date in a short month is skipped rather than moved. Recurring work retains the normal schedule proposal and confirmation lifecycle.

artisans --starter-catalog opts in to the canonical 13 starter templates and suggested source/setup needs. MCP list_artisans and REST GET /api/v1/artisans accept the same includeStarterCatalog boolean. The normal rows still contain only eligible hired workers; template IDs are not delegation UUIDs and app suggestions do not prove an account is connected. ownDigitalTwin identifies only this member's hired, non-archived Twin, with its actual status, or is null. The relative dashboardRoutes belong to the customer dashboard, not the API origin. Reading this catalog does not hire anyone, connect an app or trigger Twin/interview preparation. Use read_context for a hired Artisan's current full brief.

--wait observes bounded progress. A timeout or Ctrl-C during watch leaves accepted work running. Pause, resume, cancel, retry and reopen call explicit commands; they do not require a model or balance. Task status, available results, delivery and human acceptance remain separate facts. Evidence exposes the published factual run projection; absence of a field is not success.

Content reads return nextOffset, complete and sourceVersion. Continue with the returned offset and --source-version to keep every page bound to the same authorized view; a changed source requires starting again. context lines uses --cursor and reads all permitted saved lines when a rendered memory entry exceeds its canonical size limit. File and artifact text reads use original bytes or canonical document extraction, not search snippets; unsupported or corrupt content reports unreadable and parseNote. Inline MCP upload accepts up to 256 KiB of explicit UTF-8 or canonical base64; use the existing streaming upload for larger files. Artifact inline text is bounded to 10 MiB; the authenticated download remains available for larger artifacts.

artisan message-result returns request.artisanInstructionChanges for committed shared Artisan brief saves, with the original source message and saved revision. This differs from your private memoryChanges.instructions and workspace knowledgeChanges. An accepted message or completed reply does not prove a save. Coalesced follow-ups retain the original save source.

MCP's read_image and REST POST /api/v1/images/read expose a permitted stored file or task artifact as bounded image parts through the canonical converter. Those views may be scaled or tiled and have their own digests; originalSha256 still identifies the saved original. CLI users retrieve the unchanged original with files download or task download. Image viewing is not a new file writer or a publication operation.

artie files upload source.pdf --mime application/pdf --key upload-key --json
artie files resume upload-key --json
artie files list --query source --json
artie files show FILE_ID --json
artie files download FILE_ID --revision IMMUTABLE_REVISION --output source.pdf --hash SHA256 --json
artie task download TASK_UUID ARTIFACT_ID --output result.pdf --hash SHA256 --json
artie task email TASK_UUID EMAIL_ID --run RUN_UUID --offset 0 --json
artie request resume request-key --json

Upload streams the canonical raw byte contract with Idempotency-Key and URL-encoded X-Artie-Upload metadata. Inputs are bounded to 10 MiB; staged acceptance reports parsing as not started and the actual expiry. Upload recovery verifies the original local bytes before reusing its key. Downloads stream to a private temporary file, cap at 100 MiB, verify a supplied or published SHA-256 when available, and never overwrite an existing destination. An observed digest without a published digest is local byte evidence, not a provenance claim. Email bodies have explicit offsets and continuation offsets; read each page to obtain the full body.

Every mutation saves its target, body, query and key before sending. If the response is uncertain, recover that same key. A conflict requires reconciling current state, not replacing the key to replay an uncertain effect. Generic resume refuses person decisions; those require the interactive person flow and a current proposal. Refresh exchanges hold a private secret-free process lock. A lost rotating refresh response, or a delegated refresh response whose token fails verification, is marked uncertain in the OS store and is never automatically replayed; sign in again using the supported login flow to recover. Fresh login may clear an interrupted lock only after its recorded process has exited; an active refresh owner must finish first. Serialize login/logout for each profile.

Human operator credentials must stay on a separate OS account or device that your automation cannot access. Naming a profile operator does not isolate its credentials. The native credential is a different registered first-party client and token family; delegated automation cannot approve, enroll, revoke or record a human verdict.

artie login --operator --profile operator --origin https://api.artie.ai --client-id REGISTERED_NATIVE_PERSON_CLIENT_ID --workspace WORKSPACE_UUID
artie connections list --profile operator --json
artie connections preview --profile operator --binding NONCE --json
artie connections enroll --profile operator --binding NONCE --expected-revision 0 --key enroll-key --json
artie connections revoke GRANT_ID --profile operator --expected-revision 1 --key revoke-key --json
artie approval list TASK_UUID --profile operator --json
artie approval show DECISION_ID TASK_UUID --profile operator --kind web --json
artie approval decide DECISION_ID TASK_UUID --profile operator --kind web --expected-revision CURRENT_REVISION
artie task outcome TASK_UUID --profile operator --run RUN_UUID --expected-revision CURRENT_REVISION
artie logout --profile operator --json

Native operator login requires a separately registered first-party client and managed device flow. This optional operator route is not yet available for general customer use; make approvals and connection changes in Artie instead. Decision kinds are web, mail, calendar and schedule. Decide prints the full canonical proposal with terminal controls escaped, preserving underlying values and binding. A person selects the offered letter or approve/decline on their interactive terminal. No automatic yes mode exists. Outcomes record the selected run's human verdict through the canonical owner. Logout reports whether remote session revocation actually succeeded and clears the local credential; delegated logout alone does not revoke a standing external grant.

artie test run scenario.json --output reports/check.json --json
artie test resume reports/check.json --output reports/check.json --json

{
  "version": 1,
  "name": "Private summary check",
  "origin": "https://api.artie.ai",
  "environment": "prod",
  "workspaceId": "WORKSPACE_UUID",
  "userId": "MEMBER_UUID",
  "artisanId": "ARTISAN_UUID",
  "instructions": "Summarize these fictional figures: cash $2.4m, monthly net burn $180k. Show the runway formula. Do not contact anyone or use connected apps.",
  "idempotencyKey": "YOUR_UNIQUE_SCENARIO_KEY",
  "uploads": [],
  "steps": [],
  "waitSeconds": 120,
  "assertions": {
    "textContains": [
      "13.3"
    ],
    "artifactMin": 0,
    "expectedDisposition": "ready"
  }
}

Replace WORKSPACE_UUID and MEMBER_UUID with the IDs returned by whoami, and ARTISAN_UUID with an eligible hired Artisan ID. These fields check that the active login matches your intended account; they do not grant access. Use a new key for a new test and the saved report to resume an interrupted test.

Create scenario.json using the example above. Use your own hired Artisan ID and a private test brief that does not contact anyone or invoke connected apps. A run checks live origin, doctor environment/resource/member/client and optional exact release before the first effect. Unknown release evidence blocks a requested release pin. It persists the task and each exact prepared step before submission, then resumes that task and body after interruption. Human decisions stop with needs-person-decision; missing answers stop with needs-input. It never loads an operator profile or generates consent. Reports include canonical run/result pages, selected run, release facts and deterministic assertion evidence. Assertions expect result disposition ready by default; assertions.expectedDisposition can explicitly select partial, failed or cancelled for a corresponding test. A passing text or artifact-count assertion checks only those properties. Review the result and download any artifacts to check their contents.

Exit codes: 0 successful command/deterministic checks; 2 invalid arguments; 3 authentication/setup; 4 forbidden or hidden/not found; 5 revision/idempotency conflict; 6 waiting/interrupted observation; 7 provider/transport/execution failure or unknown outcome. --json keeps structured output on stdout and structured errors on stderr; interactive login instructions and person prompts are separate.

Use a hired Artisan UUID from artie artisans. A message uses the canonical private chat and default Auto model. It does not change task scheduling or approve a human decision.

artie artisan message --artisan ARTISAN_UUID --instructions-file request.txt --key UNIQUE_REQUEST_KEY
artie artisan message-result MESSAGE_UUID --conversation CONVERSATION_UUID
artie artisan instructions --artisan ARTISAN_UUID

For follow-ups, pass --conversation CONVERSATION_UUID when sending. A lost response resumes through the same pending request journal/key; do not submit a replacement key. Accepted means the message was saved. Read the actual reply and knowledgeChanges, memoryChanges and memorySave receipts before claiming instructions, memories or skills were saved. A succeeded turn alone is insufficient. Receipts for a turn that takes in multiple messages describe that turn. Use read_context/list_memory for full saved skill and memory readback. Personal instructions return both your all-Artisans and this-Artisan records, with current revisions.

Long replies return nextOffset; use --offset and the returned --source-version until complete is true. Text-page completion is separate from work completion or save confirmation. Use the returned normal Artie conversation for setup and human decisions.

task watch reports a finished observation for both done and needs_you. Read the status and result disposition. task show --all includes the full brief only. task result --all has a 100-page and 2.4-million-character bound; retain partial completion and continuation tokens.