@yargote/artifacts-cli 0.1.0-beta.7 → 0.1.0-beta.9

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.7
+npm install --global @yargote/artifacts-cli@0.1.0-beta.9
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.7
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.9
 artifacts --version
 ```
 
@@ -22,23 +22,26 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.7 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.7 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.9 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.9 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
 
 ## Complete first use
 
+Check `artifacts --help` for saved-connection support. With an older package that requires a server on every command, keep `ARTIFACTS_SERVER` set to the selected REST resource.
+
 An existing Artifacts account is required. Select the REST OAuth resource, which is the API origin without `/mcp`. When upgrading an older deployment, complete the [API migration](../../docs/deployment.md#migrate-the-api-hostname) before using the address below.
 
 ```sh
-export ARTIFACTS_SERVER='https://artifacts-api.yersonargotev.workers.dev'
-artifacts login
+artifacts login --server 'https://artifacts-api.yersonargotev.workers.dev'
 artifacts whoami
 ```
 
-Login opens browser authorization. After you approve access, `whoami` prints JSON with your user ID and scopes. Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine.
+Login opens browser authorization. After you approve access and the CLI verifies your identity, it saves the resolved REST resource in private state. A new terminal can run `artifacts whoami` without a server option or environment variable. It prints JSON with your user ID and scopes.
+
+Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine. This manual flow saves the connection only after identity verification succeeds.
 
 Create `snapshot.json`:
 
@@ -82,21 +85,33 @@ Run `artifacts logout` before uninstalling if you want to clear credentials. Uni
 
 Skills, help, and version commands work without a server or login. Skills commands do not read credentials or create private state. They accept and ignore global `--server` and `--state-dir` values, including their environment defaults.
 
-`--server RESOURCE` selects the exact canonical REST OAuth resource. `ARTIFACTS_SERVER` supplies the same value. Use the configured `API_URL` origin to call REST under `/v1`. The CLI has no production default and does not rewrite the supplied URL. Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
+`--server RESOURCE` overrides `ARTIFACTS_SERVER`, which overrides the connection saved by the last successful login in the selected state directory.
+
+An ordinary command override applies to that command and does not replace the saved connection. A later successful login replaces it with the verified canonical REST resource. A failed login to another server preserves the previous selection and its credentials.
+
+Login also accepts an MCP resource that advertises its REST resource. Use the configured `API_URL` origin to call REST under `/v1`.
+
+Without an override or saved connection, run `artifacts login --server RESOURCE` first. The CLI has no production default and does not rewrite the supplied URL. Existing installations keep their exact-resource credentials, but must complete a successful login to save a connection.
+
+Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
 
 A hostname change requires a new `artifacts login --server RESOURCE`. Credentials and retained operations remain bound to their exact original resource. Do not move an old operation file to the new resource or redirect its bearer requests.
 
-`--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
+`--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Each state directory has its own saved connection and credential profiles. Credentials and the saved connection share one private database, separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
 
 HTTPS is required except for HTTP on the exact loopback hosts `localhost`, `127.0.0.1`, and `[::1]`. Server URLs cannot contain credentials, a query, or a fragment.
 
 ## Authentication
 
-`artifacts login --server RESOURCE` verifies protected-resource metadata, registers a public native OAuth client, and opens browser authorization with PKCE. `--no-browser` prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
+`artifacts login --server RESOURCE` verifies protected-resource metadata. If a resource advertises `artifacts_rest_resource`, the relation may name the same resource or one distinct REST resource. Login verifies metadata for a distinct resource and prints its REST URL to stderr. The distinct resource may omit the relation or name itself, but cannot name another resource. After identity verification, login saves that REST URL for later commands. An existing `ARTIFACTS_SERVER` still overrides it. Unset the variable to use the saved connection. Login anonymously checks `<resource>/v1/identity` before registering a public native OAuth client and opening browser authorization with PKCE. This check confirms REST compatibility. Login verifies your identity again with the received token before atomically saving credentials and the connection.
+
+Errors identify the phase, method, endpoint, and HTTP status when a response exists. Network failures have no HTTP status. If the compatibility check fails, confirm the configured REST URL with your service administrator. A valid MCP metadata document alone does not establish REST compatibility.
+
+`--no-browser` runs the same checks and prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
 
 `artifacts whoami` returns the verified user, session, OAuth client, and scopes.
 
-`artifacts logout` clears local credentials and attempts to revoke the refresh token. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
+`artifacts logout` clears local credentials and attempts to revoke the refresh token. It preserves the saved connection, so `artifacts login` can reuse the server without another URL. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
 
 `ARTIFACTS_ACCESS_TOKEN` supplies an access token for automation. It does not require local login. Tokens are never command arguments or retained operation fields.
 
@@ -110,12 +125,14 @@ The private `credentials.sqlite` file stores credentials. The separate `credenti
 artifacts login [--no-browser]
 artifacts logout
 artifacts whoami
-artifacts create --snapshot FILE [--project NAME] [--request-id ID]
+artifacts create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
                  [--response full|compact]
 artifacts create --command FILE
 artifacts list [--limit N] [--cursor CURSOR] [--project NAME]
 artifacts projects
 artifacts read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+artifacts read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+               [--out FILE [--quiet]]
 artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
                  [--response full|compact]
 artifacts update [ID] --command FILE
@@ -124,8 +141,7 @@ artifacts history ID [--limit N] [--before-sequence N] [--summary]
 artifacts publish ID --revision REV --expected-version N [--request-id ID]
 artifacts publish [ID] --command FILE
 artifacts export ID --revision REV --out FILE
-artifacts move ID --project NAME [--request-id ID]
-artifacts move ID --no-project [--request-id ID]
+artifacts move ID [--project NAME | --no-project] [--slug SLUG | --no-slug] [--request-id ID]
 artifacts share ID --email EMAIL [--notify] [--request-id ID]
 artifacts shares ID
 artifacts unshare ID SHARE_ID [--request-id ID]
@@ -198,10 +214,26 @@ artifacts move ARTIFACT_ID --no-project
 
 Every artifact read and list item includes `project`, a name or null. `projects` prints `{ "items": [{ "name": "Alpha", "artifactCount": 1 }] }`, ordered by name without regard to letter case. A project exists only while it contains an artifact.
 
-`move ID` requires exactly one of `--project NAME` or `--no-project`. It prints `{ "artifactId": "...", "project": "Beta" }` with the stored spelling, or `null` after `--no-project`. Move never creates a revision or changes the publication. Moving to the current project succeeds without change. Move is a retained mutation like the others, so `retry` recovers a lost response.
+`move ID` requires at least one of `--project NAME`, `--no-project`, `--slug SLUG`, or `--no-slug`, and accepts at most one from each pair. An option left out keeps that value. It prints `{ "artifactId": "...", "project": "Beta" }` with the stored spelling, or `null` after `--no-project`. Move never creates a revision or changes the publication. Moving to the current project succeeds without change. Move is a retained mutation like the others, so `retry` recovers a lost response.
 
 Version `0.1.0-beta.4` and earlier parse artifact responses strictly and fail with `invalid_response` against a server that returns `project`. Upgrade the CLI together with the server.
 
+## Slugs
+
+A slug names a page within its project, so `read` can find it without its ID. `create --slug SLUG` sets it. A slug contains 1 to 160 characters of lowercase ASCII kebab-case segments separated by `/`, such as `concepts/rag` or `index`. It is never normalized, and a trailing `.md` is rejected with a hint to remove it. A complete create command file can include the same optional `slug` field.
+
+```sh
+artifacts create --snapshot snapshot.json --project Mi-Wiki --slug concepts/rag
+artifacts read --project mi-wiki --slug concepts/rag
+artifacts read --slug index
+artifacts move ARTIFACT_ID --slug concepts/retrieval
+artifacts move ARTIFACT_ID --no-slug
+```
+
+A slug is unique within the owner's project, matched by the project's stored spelling. Artifacts without a project share one unfiled namespace, which `read --slug` reads without `--project`. `read` takes exactly one of an ID or `--slug`, and `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId`. A locator with no artifact fails with `not_found`. Every artifact read and list item includes `slug`, a name or null. Version `0.1.0-beta.7` and earlier reject responses that include `slug` with `invalid_response`.
+
+`move ID --slug SLUG` renames a page in its project, and `move ID --no-slug` clears the slug. A move to another project keeps the slug. A move fails with `slug_conflict`, status 409, and the holder's `artifactId` when the target project already uses the target slug, and then changes nothing. A slug change creates no revision. Verify the new slug with `read`. The move result is unchanged, so published CLI versions keep working against this server.
+
 ## Share publication access
 
 These commands are available from `0.1.0-beta.6`. Check installed help for support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.9",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,8 +27,8 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.7",
-    "@yargote/artifacts-client": "0.1.0-beta.7",
+    "@yargote/artifacts-contracts": "0.1.0-beta.9",
+    "@yargote/artifacts-client": "0.1.0-beta.9",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -9,7 +9,7 @@ Use the installed `artifacts` executable. Run `artifacts --help` and read [the c
 
 ## Select the account and resource
 
-Use the resource selected by the user or the existing `ARTIFACTS_SERVER` environment value. Pass `--server RESOURCE` or set `ARTIFACTS_SERVER` for service commands. Skills, help, and version commands work offline without a server or login. Login does not set an implicit default. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
+Use the resource selected by the user. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful login in the selected private state directory. Ordinary command overrides do not replace that connection. Skills, help, and version commands work offline without a server or login. Check installed help for saved-connection support. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
 
 Run `artifacts whoami` before the first mutation when the current identity is not established. Keep the selected resource and owner consistent throughout one operation. If login is needed, use `artifacts login --server RESOURCE`. The user authenticates in the browser. Do not collect their password or read another application's credentials. Never put tokens in command arguments, operation files, logs, or the final reply.
 
@@ -35,6 +35,8 @@ Use `edit` for partial changes that preserve omitted fields. Use `update` for a
 
 When the user names a project for new content, add `--project NAME` to `create`. Run `artifacts projects` first when an existing project may already fit. A name matching an existing project regardless of letter case joins it and keeps the stored spelling. Do not invent a project the user did not ask for. Use `list --project NAME` to find artifacts in a project.
 
+When the user names a page, add `--slug SLUG` such as `concepts/rag` to `create`, and read it later with `read --project NAME --slug SLUG`, or `read --slug SLUG` for an unfiled page, instead of listing for its ID. Omit the `.md` suffix. A `slug_conflict` error names the `artifactId` that already holds the slug in that project. Rename a page with `move ID --slug SLUG` and clear its slug with `move ID --no-slug`. A move to another project keeps the slug, and a move into a used slug fails with `slug_conflict` without changing anything.
+
 Use `move ID --project NAME` to file an existing artifact under a project and `move ID --no-project` to remove it from one. A move changes only the project. It creates no revision and leaves the publication unchanged. It is a retained mutation, so recover an uncertain move with `retry`. Verify it with `read` or `list --project NAME`. A project disappears when its last artifact leaves it.
 
 ## Publish deliberately

package/skills/artifacts-cli/references/commands.md

@@ -24,16 +24,17 @@ The published `0.1.0-beta.1` package predates skills commands. Do not assume sup
 ## Authenticate
 
 ```sh
-export ARTIFACTS_SERVER=https://artifacts.example.test/mcp
-artifacts login
+artifacts login --server https://artifacts.example.test/mcp
 artifacts whoami
 ```
 
-Replace the example with the selected resource before executing it. Service commands read `ARTIFACTS_SERVER` or an explicit `--server RESOURCE`. Login does not save a default resource. `--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
+Replace the example with the selected resource before executing it. Service commands select `--server RESOURCE` before `ARTIFACTS_SERVER`, then the connection saved by a successful identity-verified login. Ordinary overrides do not replace the saved connection. A later successful login replaces it with the verified REST resource. A failed login to another server preserves the previous connection and its credentials. Check installed help for saved-connection support.
+
+`--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
 
 Use `--no-browser` when the environment cannot open a browser automatically. Open the printed authorization URL and keep the CLI running for its loopback callback. A remote machine's loopback callback must be reachable by the browser used for login. Do not replace the callback with an arbitrary public listener.
 
-`logout` clears local credentials and attempts refresh-token revocation. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
+`logout` clears local credentials and attempts refresh-token revocation. It keeps the saved connection, so a later `artifacts login` can reuse it. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
 
 ## Create a complete snapshot
 
@@ -103,7 +104,23 @@ artifacts move ARTIFACT_ID --no-project
 
 A project name contains 1 to 80 characters after trimming and NFC normalization, without control characters. A name that matches an existing project regardless of letter case joins it and keeps its stored spelling. Every read and list item includes `project`, a name or null. `projects` prints `{ "items": [{ "name": "Client onboarding", "artifactCount": 1 }] }`, ordered by name without regard to letter case. A project exists only while it contains an artifact.
 
-`move` takes exactly one of `--project NAME` or `--no-project` and prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. It creates no revision and leaves the publication unchanged. Moving to the current project succeeds without change. A lost move response is recovered with `retry REQUEST_ID` like any other retained mutation.
+`move` takes at least one of `--project NAME`, `--no-project`, `--slug SLUG`, or `--no-slug`, and at most one from each pair. It prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. An option left out keeps that value. It creates no revision and leaves the publication unchanged. Moving to the current project succeeds without change. A lost move response is recovered with `retry REQUEST_ID` like any other retained mutation.
+
+## Name pages with slugs
+
+Check that installed help lists `--slug` before using it.
+
+```sh
+artifacts create --snapshot snapshot.json --project "Mi wiki" --slug concepts/rag
+artifacts read --project "mi wiki" --slug concepts/rag
+artifacts read --slug index
+artifacts move ARTIFACT_ID --slug concepts/retrieval
+artifacts move ARTIFACT_ID --no-slug
+```
+
+A slug contains 1 to 160 characters of lowercase ASCII kebab-case segments separated by `/`, such as `concepts/rag` or `index`. It is never normalized, and a trailing `.md` is rejected with a hint to remove it. A slug is unique within the owner's project, matched by the project's stored spelling. Artifacts without a project share one unfiled namespace, which `read --slug` without `--project` reads. Every read and list item includes `slug`, a name or null.
+
+`read` takes exactly one of an ID or `--slug`. `--project` applies only with `--slug`. A used slug fails `create` with `slug_conflict`, status 409, and the holder's `artifactId` in `details`. A locator with no artifact fails with `not_found`. `move ID --slug SLUG` renames a page in its project, and `move ID --no-slug` clears the slug. A move to another project keeps the slug unless `--slug` or `--no-slug` changes it. A move fails with `slug_conflict` and changes nothing when the target project already uses the target slug. A slug change creates no revision.
 
 ## Edit without losing retained data
 
@@ -134,7 +151,7 @@ Command files contain the command itself, without the CLI's retained-operation w
 | `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
 | `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
 
-`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name and an optional `slug`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
 
 ```json
 {

package/src/auth.d.ts

@@ -4,7 +4,10 @@ export declare function login(options: {
     stateDir: string;
     noBrowser: boolean;
     onAuthorizationUrl: (url: string) => void;
-}): Promise<Identity>;
+}): Promise<{
+    resource: string;
+    identity: Identity;
+}>;
 export declare function accessToken(options: {
     resource: string;
     stateDir: string;

package/src/auth.js

@@ -2,13 +2,12 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import * as oidc from 'openid-client';
-import { canonicalResource, identitySchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
-import { z } from 'zod';
+import { canonicalResource, httpErrorSchema, identitySchema, protectedResourceMetadataSchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
+import { HttpError } from '@yargote/artifacts-client';
 import { CredentialStore } from "./credentials.js";
 const networkTimeout = 10_000;
 const callbackTimeout = 180_000;
 const scopes = 'openid profile offline_access artifacts:read artifacts:write artifacts:publish';
-const resourceMetadata = z.object({ resource: z.string(), authorization_servers: z.array(z.string()).min(1) });
 function endpoint(value, issuer) {
     const url = new URL(value);
     const loopback = /^http:\/\/(?:127\.0\.0\.1|\[::1\]|localhost)(?::[0-9]+)?(?:\/|$)/.test(value);
@@ -18,12 +17,34 @@ function endpoint(value, issuer) {
         throw new Error('OAuth endpoints must use the issuer origin');
     return url;
 }
-async function boundedFetch(url, options = {}) {
-    const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(networkTimeout)]) : AbortSignal.timeout(networkTimeout);
-    const response = await fetch(url, { ...options, redirect: 'manual', signal });
+class AuthTransportError extends Error {
+}
+function safeUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return '[invalid endpoint]';
+    }
+}
+function authFailure(context, code, explanation, status) {
+    const message = `${context.phase} ${context.method} ${safeUrl(context.url)}${status === undefined ? '' : ` HTTP ${status}`}: ${explanation}`;
+    return status === undefined ? new AuthTransportError(message) : new HttpError(status, code, message);
+}
+async function boundedFetch(context, options = {}) {
+    const timeout = AbortSignal.timeout(networkTimeout);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await fetch(context.url, { ...options, redirect: 'manual', signal });
+    }
+    catch {
+        throw authFailure(context, 'network_error', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Request timed out' : options.signal?.aborted ? 'Request cancelled' : 'Network request failed');
+    }
     if (response.status >= 300 && response.status < 400) {
-        await response.body?.cancel();
-        throw new Error('Authentication redirects are not allowed');
+        await response.body?.cancel().catch(() => { });
+        throw authFailure(context, 'redirect_refused', 'Redirect refused', response.status);
     }
     const reader = response.body?.getReader();
     const chunks = [];
@@ -36,13 +57,13 @@ async function boundedFetch(url, options = {}) {
                     break;
                 size += chunk.value.byteLength;
                 if (size > 1024 * 1024)
-                    throw new Error('Authentication response is too large');
+                    throw new Error('too large');
                 chunks.push(chunk.value);
             }
         }
-        catch (error) {
+        catch {
             await reader.cancel().catch(() => { });
-            throw error;
+            throw authFailure(context, 'invalid_response', timeout.aborted || (options.signal?.aborted && options.signal.reason instanceof DOMException && options.signal.reason.name === 'TimeoutError') ? 'Response timed out' : options.signal?.aborted ? 'Request cancelled' : 'Cannot read response', response.status);
         }
         finally {
             reader.releaseLock();
@@ -50,31 +71,155 @@ async function boundedFetch(url, options = {}) {
     }
     return new Response(size ? Buffer.concat(chunks) : null, { status: response.status, statusText: response.statusText, headers: response.headers });
 }
-function discoveryOptions(issuer, signal) {
+function jsonResponse(response, context) {
+    if (response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json')
+        throw authFailure(context, 'invalid_response', 'Expected a JSON response', response.status);
+    return response.json().catch(() => { throw authFailure(context, 'invalid_response', 'Invalid JSON response', response.status); });
+}
+async function discoverResource(resource, terminal = false) {
+    const context = { phase: 'resource_metadata', method: 'GET', url: protectedResourceMetadataUrl(resource) };
+    const response = await boundedFetch(context);
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'Resource metadata service failed' : 'Cannot discover the protected resource. Confirm the configured REST URL', response.status);
+    const document = await jsonResponse(response, context);
+    const parsed = protectedResourceMetadataSchema.safeParse(document);
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid protected resource metadata', response.status);
+    if (parsed.data.resource !== resource)
+        throw authFailure(context, 'invalid_response', 'Protected resource metadata does not match the exact server URL', response.status);
+    if (terminal && parsed.data.artifacts_rest_resource !== undefined && parsed.data.artifacts_rest_resource !== resource)
+        throw authFailure(context, 'invalid_response', 'REST resource metadata must not advertise another artifacts_rest_resource', response.status);
+    const issuer = parsed.data.authorization_servers[0];
+    try {
+        endpoint(issuer);
+    }
+    catch {
+        throw authFailure(context, 'invalid_response', 'Invalid authorization server URL in protected resource metadata', response.status);
+    }
+    return { issuer, ...(parsed.data.artifacts_rest_resource === undefined ? {} : { restResource: parsed.data.artifacts_rest_resource }) };
+}
+function compatibleChallenge(value) {
+    if (!value)
+        return false;
+    const match = /^Bearer\s+(.+)$/i.exec(value);
+    if (!match)
+        return false;
+    const parameters = new Map();
+    const input = match[1];
+    const parameter = /\s*([!#$%&'*+.^_`|~0-9A-Za-z-]+)\s*=\s*(?:"((?:[^"\\]|\\[\x20-\x7e])*)"|([!#$%&'*+.^_`|~0-9A-Za-z-]+))\s*(,|$)/gy;
+    let position = 0;
+    while (position < input.length) {
+        parameter.lastIndex = position;
+        const param = parameter.exec(input);
+        if (!param || (param[4] === ',' && parameter.lastIndex === input.length))
+            return false;
+        const key = param[1].toLowerCase();
+        if (parameters.has(key))
+            return false;
+        parameters.set(key, param[2] === undefined ? param[3] : param[2].replace(/\\([\x20-\x7e])/g, '$1'));
+        position = parameter.lastIndex;
+    }
+    return parameters.get('error') === 'invalid_token' && (parameters.get('scope')?.split(/\s+/).includes('artifacts:read') ?? false);
+}
+async function checkIdentity(resource, request) {
+    const context = { phase: request.kind === 'anonymous' ? 'rest_preflight' : 'authenticated_identity', method: 'GET', url: `${restBase(resource)}/identity` };
+    const response = await boundedFetch(context, request.kind === 'anonymous' ? {} : { signal: request.signal, headers: { authorization: `Bearer ${request.accessToken}` } });
+    if (request.kind === 'anonymous') {
+        if (response.status === 401) {
+            const body = httpErrorSchema.safeParse(await jsonResponse(response, context));
+            if (body.success && body.data.error.code === 'unauthenticated' && compatibleChallenge(response.headers.get('www-authenticate')))
+                return;
+        }
+        throw authFailure(context, response.status >= 500 ? 'service_error' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : 'REST identity route is incompatible. Use the exact REST URL or configure artifacts_rest_resource on the MCP server', response.status);
+    }
+    if (!response.ok)
+        throw authFailure(context, response.status >= 500 ? 'service_error' : response.status === 401 || response.status === 403 ? 'access_denied' : 'incompatible_resource', response.status >= 500 ? 'REST identity service failed' : response.status === 401 || response.status === 403 ? 'OAuth grant cannot access this Artifacts server' : 'REST identity route is unavailable. Confirm the configured REST URL', response.status);
+    const parsed = identitySchema.safeParse(await jsonResponse(response, context));
+    if (!parsed.success)
+        throw authFailure(context, 'invalid_response', 'Invalid REST identity response', response.status);
+    if (request.claims.sub !== parsed.data.userId || (request.claims.sid !== undefined && request.claims.sid !== parsed.data.sessionId))
+        throw authFailure(context, 'invalid_response', 'OAuth identity does not match the Artifacts session', response.status);
+    return parsed.data;
+}
+async function oauth(issuer, signal, operation) {
+    const observations = [];
+    try {
+        const result = await operation(discoveryOptions(issuer, signal, observations));
+        if (result instanceof oidc.Configuration) {
+            validateConfiguration(result, issuer, observations);
+            result[oidc.customFetch] = discoveryOptions(issuer, signal)[oidc.customFetch];
+        }
+        return result;
+    }
+    catch (error) {
+        let cause = error;
+        let observed;
+        for (let depth = 0; depth < 5; depth++) {
+            if (cause instanceof HttpError || cause instanceof AuthTransportError)
+                throw cause;
+            const response = cause instanceof Response ? cause : cause instanceof Error && 'response' in cause ? cause.response : undefined;
+            if (response instanceof Response)
+                observed = observations.find((item) => item.response === response);
+            if (observed || !(cause instanceof Error))
+                break;
+            cause = cause.cause;
+        }
+        observed ??= observations.at(-1);
+        if (observed)
+            throw authFailure(observed.context, 'invalid_response', 'OAuth protocol validation failed', observed.response.status);
+        throw new Error('OAuth protocol validation failed');
+    }
+}
+function discoveryOptions(issuer, signal, observations) {
     endpoint(issuer);
     return {
         timeout: networkTimeout / 1000,
         execute: [...(new URL(issuer).protocol === 'http:' ? [oidc.allowInsecureRequests] : []), oidc.enableNonRepudiationChecks],
-        [oidc.customFetch]: (url, options) => boundedFetch(endpoint(url, issuer), { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body }),
+        [oidc.customFetch]: async (url, options) => {
+            const context = { phase: 'oauth', method: options.method ?? 'GET', url };
+            try {
+                endpoint(url, issuer);
+            }
+            catch {
+                throw authFailure({ ...context, url: issuer }, 'invalid_response', 'Invalid OAuth endpoint');
+            }
+            const response = await boundedFetch(context, { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body });
+            if (!response.ok)
+                throw authFailure(context, response.status >= 500 ? 'service_error' : 'oauth_error', response.status >= 500 ? 'OAuth service failed' : 'OAuth request failed', response.status);
+            observations?.push({ context, response });
+            return response;
+        },
     };
 }
-function validateConfiguration(config, issuer) {
+function validateConfiguration(config, issuer, observations) {
+    const discovery = observations.find((item) => item.context.method === 'GET');
+    const registration = observations.find((item) => item.context.method === 'POST');
+    if (!discovery)
+        throw new Error('OAuth discovery response was not observed');
+    const failDiscovery = (message) => authFailure(discovery.context, 'invalid_response', message, discovery.response.status);
     const metadata = config.serverMetadata();
     if (metadata.issuer !== issuer)
-        throw new Error('OAuth issuer metadata does not match the configured issuer');
+        throw failDiscovery('OAuth issuer metadata does not match the configured issuer');
     for (const [key, value] of Object.entries(metadata)) {
-        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string')
-            endpoint(value, issuer);
+        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string') {
+            try {
+                endpoint(value, issuer);
+            }
+            catch (error) {
+                const message = error instanceof Error && error.message === 'OAuth endpoints must use the issuer origin' ? error.message : 'OAuth URLs require HTTPS or an exact loopback HTTP host, without credentials, query, or fragment';
+                throw failDiscovery(message);
+            }
+        }
     }
     if (!metadata.authorization_endpoint || !metadata.token_endpoint)
-        throw new Error('OAuth metadata is missing authorization or token endpoints');
-    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none')
-        throw new Error('The CLI requires a public OAuth client without a secret');
+        throw failDiscovery('OAuth metadata is missing authorization or token endpoints');
+    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none') {
+        const message = 'The CLI requires a public OAuth client without a secret';
+        throw registration ? authFailure(registration.context, 'invalid_response', message, registration.response.status) : new Error(message);
+    }
 }
 async function configuration(registration, signal) {
-    const config = await oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), discoveryOptions(registration.issuer, signal));
-    validateConfiguration(config, registration.issuer);
-    return config;
+    return oauth(registration.issuer, signal, (options) => oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), options));
 }
 function tokenRecord(tokens, previousRefresh) {
     if (typeof tokens.expires_in !== 'number' || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0)
@@ -142,7 +287,11 @@ async function openBrowser(url) {
     });
 }
 export async function login(options) {
-    const resource = canonicalResource(options.resource);
+    const source = canonicalResource(options.resource);
+    const metadata = await discoverResource(source);
+    const resource = metadata.restResource ?? source;
+    const { issuer } = resource === source ? metadata : await discoverResource(resource, true);
+    await checkIdentity(resource, { kind: 'anonymous' });
     const store = await CredentialStore.open(options.stateDir);
     let listener;
     try {
@@ -151,14 +300,6 @@ export async function login(options) {
             store.write(resource, { ...profile, epoch: profile.epoch + 1 });
             return profile.epoch + 1;
         });
-        const response = await boundedFetch(protectedResourceMetadataUrl(resource));
-        if (!response.ok)
-            throw new Error('Cannot discover the protected resource');
-        const metadata = resourceMetadata.parse(await response.json());
-        if (metadata.resource !== resource)
-            throw new Error('Protected resource metadata does not match the exact server URL');
-        const issuer = metadata.authorization_servers[0];
-        endpoint(issuer);
         listener = await callback();
         const { redirectUri, signal } = listener;
         const config = await store.exclusive(async () => {
@@ -167,11 +308,10 @@ export async function login(options) {
                 throw new Error('Login was superseded by another login or logout');
             if (profile.registration?.issuer === issuer)
                 return configuration(profile.registration, signal);
-            const registered = await oidc.dynamicClientRegistration(new URL(issuer), {
+            const registered = await oauth(issuer, signal, (options) => oidc.dynamicClientRegistration(new URL(issuer), {
                 client_name: 'Artifacts CLI', application_type: 'native', token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA',
                 redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], scope: scopes,
-            }, oidc.None(), discoveryOptions(issuer, signal));
-            validateConfiguration(registered, issuer);
+            }, oidc.None(), options));
             store.write(resource, { ...profile, registration: { issuer, clientId: registered.clientMetadata().client_id }, tokens: null, refreshAttempt: null });
             return registered;
         });
@@ -187,22 +327,21 @@ export async function login(options) {
         if (!options.noBrowser)
             await openBrowser(authorizationUrl);
         const currentUrl = await authorization;
+        if (currentUrl.searchParams.has('error'))
+            throw new Error(currentUrl.searchParams.get('error') === 'access_denied' ? 'Authorization denied' : 'Authorization failed');
         return await store.exclusive(async () => {
             const profile = store.read(resource);
             if (profile.epoch !== epoch)
                 throw new Error('Login was superseded by another login or logout');
-            const tokens = await oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            const tokens = await oauth(issuer, signal, (options) => {
+                config[oidc.customFetch] = options[oidc.customFetch];
+                return oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            });
             const credentials = tokenRecord(tokens);
-            const identityResponse = await boundedFetch(`${restBase(resource)}/identity`, { signal, headers: { authorization: `Bearer ${credentials.accessToken}` } });
-            if (!identityResponse.ok)
-                throw new Error('The OAuth grant cannot access this Artifacts server');
-            const identity = identitySchema.parse(await identityResponse.json());
-            const claims = tokens.claims();
-            if (claims.sub !== identity.userId || (claims.sid !== undefined && claims.sid !== identity.sessionId))
-                throw new Error('OAuth identity does not match the Artifacts session');
+            const identity = await checkIdentity(resource, { kind: 'authenticated', accessToken: credentials.accessToken, signal, claims: tokens.claims() });
             signal.throwIfAborted();
-            store.write(resource, { ...profile, tokens: credentials, refreshAttempt: null });
-            return identity;
+            store.commitLogin(resource, epoch, credentials);
+            return { resource, identity };
         });
     }
     finally {

package/src/credentials.d.ts

@@ -32,6 +32,8 @@ export declare class CredentialStore {
     exclusive<T>(work: () => T | Promise<T>): Promise<T>;
     read(resource: string): CredentialProfile;
     write(resource: string, profile: CredentialProfile): void;
+    readSelectedResource(): string | undefined;
+    commitLogin(resource: string, epoch: number, tokens: Tokens): void;
     close(): void;
 }
 export {};

package/src/credentials.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { setTimeout as delay } from 'node:timers/promises';
 import { z } from 'zod';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const registrationSchema = z.strictObject({ issuer: z.string(), clientId: z.string().min(1) });
 const tokensSchema = z.strictObject({ accessToken: z.string().min(1), refreshToken: z.string().min(1).optional(), expiresAt: z.number().finite() });
 const profileSchema = z.strictObject({
@@ -50,6 +51,7 @@ export class CredentialStore {
             await store.exclusive(() => {
                 data.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;');
                 data.exec('CREATE TABLE IF NOT EXISTS profiles (resource TEXT PRIMARY KEY, profile TEXT NOT NULL) STRICT');
+                data.exec('CREATE TABLE IF NOT EXISTS selected_resource (id INTEGER PRIMARY KEY CHECK (id = 1), resource TEXT NOT NULL) STRICT');
             });
             return store;
         }
@@ -90,5 +92,25 @@ export class CredentialStore {
     write(resource, profile) {
         this.data.prepare('INSERT INTO profiles(resource, profile) VALUES (?, ?) ON CONFLICT(resource) DO UPDATE SET profile = excluded.profile').run(resource, JSON.stringify(profileSchema.parse(profile)));
     }
+    readSelectedResource() {
+        const row = this.data.prepare('SELECT resource FROM selected_resource WHERE id = 1').get();
+        return row ? canonicalResource(String(row.resource)) : undefined;
+    }
+    commitLogin(resource, epoch, tokens) {
+        canonicalResource(resource);
+        this.data.exec('BEGIN IMMEDIATE');
+        try {
+            const profile = this.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            this.write(resource, { ...profile, tokens, refreshAttempt: null });
+            this.data.prepare('INSERT INTO selected_resource(id, resource) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET resource = excluded.resource').run(resource);
+            this.data.exec('COMMIT');
+        }
+        catch (error) {
+            this.data.exec('ROLLBACK');
+            throw error;
+        }
+    }
     close() { this.data.close(); this.lock.close(); }
 }

package/src/index.js

@@ -10,12 +10,14 @@ import { createSchema, listSharesSchema, moveSchema, publishSchema, shareSchema,
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
+import { CredentialStore } from "./credentials.js";
 import { loadOperation, retainOperation, submitOperation } from "./operations.js";
 import { runSkillsCommand } from "./skills.js";
 const help = `Usage: artifacts COMMAND [OPTIONS]
 
 Global options:
-  --server RESOURCE       Canonical OAuth resource, or ARTIFACTS_SERVER
+  --server RESOURCE       Exact REST OAuth resource, or ARTIFACTS_SERVER
+                         Defaults to the last successful login
   --state-dir DIR         Private local state, or ARTIFACTS_STATE_DIR
                          Default: ~/.local/state/artifacts
   --help                 Print this reference
@@ -30,12 +32,14 @@ Commands:
   login [--no-browser]
   logout
   whoami
-  create --snapshot FILE [--project NAME] [--request-id ID]
+  create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
          [--response full|compact]
   create --command FILE
   list [--limit N] [--cursor CURSOR] [--project NAME]
   projects
   read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+  read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+         [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
   update [ID] --command FILE
@@ -44,8 +48,8 @@ Commands:
   publish ID --revision REV --expected-version N [--request-id ID]
   publish [ID] --command FILE
   export ID --revision REV --out FILE
-  move ID --project NAME [--request-id ID]
-  move ID --no-project [--request-id ID]
+  move ID [--project NAME | --no-project] [--slug SLUG | --no-slug]
+         [--request-id ID]
   share ID --email EMAIL [--notify] [--request-id ID]
   shares ID
   unshare ID SHARE_ID [--request-id ID]
@@ -55,12 +59,29 @@ Mutation command files contain the complete create, update, or publish JSON.
 Mutation request IDs default to a random UUID. Commands are retained before
 submission. Retry sends the exact retained command for the same server and owner.
 Projects group artifacts by name without regard to letter case. A project
-exists while it contains an artifact. Move changes the project of an artifact
-without creating a revision; --no-project removes it from its project.
+exists while it contains an artifact. Move changes the project or the slug of
+an artifact without creating a revision. It needs at least one of its four
+options. --no-project removes the artifact from its project, and --no-slug
+clears its slug. An option left out keeps that value, so a move to another
+project keeps the slug.
+A slug such as concepts/rag names an artifact within its project, or within
+the unfiled artifacts without --project. Read --slug finds it without its ID.
+Create or move fails with slug_conflict when the project already uses the slug.
 Read --out saves the returned artifact JSON. Export --out saves the ZIP.
 Read --quiet requires --out and suppresses successful JSON stdout.
 Output files are created exclusively and never overwrite an existing path.
 JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+Login accepts an MCP URL when its metadata advertises artifacts_rest_resource.
+Split MCP and REST resources require this relation. Login remembers the verified
+REST URL for later commands. --server takes precedence over ARTIFACTS_SERVER,
+which takes precedence over the saved URL. Ordinary overrides do not replace
+the saved URL. Logout keeps it for a later login.
+Login checks <resource>/v1/identity before browser
+authorization. Legacy /mcp
+resources work when their REST API is at /mcp/v1. If the check fails, confirm
+the configured REST URL with your service administrator.
+Login errors report the phase, method, endpoint, and HTTP status when received.
+Network failures have no HTTP status. Login verifies identity again after OAuth.
 ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
 Skills commands work offline without a server, login, or private state.
 They print plain text. Global server and state options are accepted and ignored.
@@ -73,13 +94,13 @@ class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
-    create: ['snapshot', 'project', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor', 'project'], projects: [], read: ['revision', 'response', 'out', 'quiet'],
+    create: ['snapshot', 'project', 'slug', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], read: ['slug', 'project', 'revision', 'response', 'out', 'quiet'],
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
     share: ['email', 'notify', 'request-id'], shares: [], unshare: ['request-id'],
-    export: ['revision', 'out'], move: ['project', 'no-project', 'request-id'], retry: [],
+    export: ['revision', 'out'], move: ['project', 'no-project', 'slug', 'no-slug', 'request-id'], retry: [],
     skills: ['full', 'all', 'agent', 'global', 'force'],
 };
 async function jsonFile(path) {
@@ -116,7 +137,7 @@ async function main() {
             summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
             full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
             global: { type: 'boolean' }, force: { type: 'boolean' },
-            project: { type: 'string' }, 'no-project': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, slug: { type: 'string' }, 'no-slug': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -144,11 +165,20 @@ async function main() {
             throw new UsageError(`Option --${option} is not supported by ${command}`);
     if (command === 'skills')
         return runSkillsCommand(arguments_, values, seen);
-    const resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
-    if (!resourceValue)
-        throw new UsageError('Specify --server RESOURCE or ARTIFACTS_SERVER. No production server is selected by default.');
-    const resource = canonicalResource(resourceValue);
     const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    let resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (resourceValue === undefined) {
+        const store = await CredentialStore.open(stateDir);
+        try {
+            resourceValue = await store.exclusive(() => store.readSelectedResource());
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (resourceValue === undefined)
+        throw new UsageError('No server is saved. Run artifacts login --server RESOURCE or set ARTIFACTS_SERVER.');
+    const resource = canonicalResource(resourceValue);
     function argument(required = true) {
         if (arguments_.length > 1 || (required && arguments_.length !== 1))
             throw new UsageError(`${command} requires ${required ? 'one' : 'zero or one'} positional argument`);
@@ -172,6 +202,11 @@ async function main() {
             throw new UsageError(`--${name} requires a nonnegative safe integer`);
         return Number(value);
     }
+    function cleared(name, value, clear) {
+        if (value !== undefined && clear)
+            throw new UsageError(`Specify at most one of --${name} or --no-${name}`);
+        return clear ? null : value;
+    }
     const response = values.response;
     if (response !== undefined && response !== 'full' && response !== 'compact')
         throw new UsageError('--response requires full or compact');
@@ -204,7 +239,12 @@ async function main() {
     switch (command) {
         case 'login':
             none();
-            return login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+            {
+                const result = await login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+                if (result.resource !== resource)
+                    process.stderr.write(`REST resource: ${result.resource}\nThis verified REST URL is saved for subsequent commands.\n`);
+                return result.identity;
+            }
         case 'logout':
             none();
             return logout({ resource, stateDir });
@@ -215,7 +255,7 @@ async function main() {
             if (values.command)
                 return mutate(await commandFile('create'));
             none();
-            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(response === undefined ? {} : { response }) }) });
+            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(values.slug === undefined ? {} : { slug: values.slug }), ...(response === undefined ? {} : { response }) }) });
         }
         case 'list':
             none();
@@ -224,7 +264,12 @@ async function main() {
             none();
             return client.projects();
         case 'read': {
-            const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.slug === undefined && values.project !== undefined)
+                throw new UsageError('read --project requires --slug');
+            if ((values.slug === undefined) !== (arguments_.length === 1) || arguments_.length > 1)
+                throw new UsageError('read requires exactly one of an artifact ID or --slug SLUG');
+            const target = values.slug === undefined ? { artifactId: arguments_[0] } : { slug: values.slug, ...(values.project === undefined ? {} : { project: values.project }) };
+            const result = await client.read({ ...target, ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
                 await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
             return quiet ? undefined : result;
@@ -255,9 +300,11 @@ async function main() {
         }
         case 'move': {
             const artifactId = argument();
-            if ((values.project !== undefined) === (values['no-project'] ?? false))
-                throw new UsageError('Specify exactly one of --project NAME or --no-project');
-            return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), project: values.project ?? null }) });
+            const project = cleared('project', values.project, values['no-project']);
+            const slug = cleared('slug', values.slug, values['no-slug']);
+            if (project === undefined && slug === undefined)
+                throw new UsageError('move requires --project NAME, --no-project, --slug SLUG, or --no-slug');
+            return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), ...(project === undefined ? {} : { project }), ...(slug === undefined ? {} : { slug }) }) });
         }
         case 'share': return mutate({ kind: 'share', command: shareSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), email: required('email'), ...(values.notify === undefined ? {} : { notify: values.notify }) }) });
         case 'shares': return client.listShares(listSharesSchema.parse({ artifactId: argument() }));

package/src/operations.d.ts

@@ -31,6 +31,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>;
         project: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
         response: z.ZodOptional<z.ZodEnum<{
             full: "full";
             compact: "compact";
@@ -94,7 +95,8 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     command: z.ZodObject<{
         requestId: z.ZodString;
         artifactId: z.ZodString;
-        project: z.ZodNullable<z.ZodString>;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>;
     version: z.ZodLiteral<1>;
     resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;