@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/utils/pagination/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pagination utilities for CLI output.
+ *
+ * Re-exports the core pagination function, types, and the default
+ * terminal I/O factory for interactive keypress reading.
+ *
+ * @module utils/pagination
+ */
+export { paginateOutput } from './paginate-output.js';
+export type { PaginationIO, PaginateOptions, PaginateResult } from './paginate-output.js';
+export { createDefaultIO } from './keypress-reader.js';

package/lib/utils/pagination/index.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Pagination utilities for CLI output.
+ *
+ * Re-exports the core pagination function, types, and the default
+ * terminal I/O factory for interactive keypress reading.
+ *
+ * @module utils/pagination
+ */
+export { paginateOutput } from './paginate-output.js';
+export { createDefaultIO } from './keypress-reader.js';
+//# sourceMappingURL=index.js.map

package/lib/utils/pagination/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/pagination/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/utils/pagination/keypress-reader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Raw keypress reader for interactive terminal pagination.
+ *
+ * Provides a {@link PaginationIO} implementation that reads single keypresses
+ * from process.stdin in raw mode. Handles Ctrl+C gracefully and restores
+ * terminal state on exit.
+ *
+ * @module utils/pagination/keypress-reader
+ */
+import type { PaginationIO } from './paginate-output.js';
+/**
+ * Create the default terminal I/O implementation for pagination.
+ *
+ * Uses `process.stdin.setRawMode(true)` to read individual keypresses.
+ * Registers a `process.on('exit')` handler to restore stdin state unconditionally.
+ * Handles `\x03` (Ctrl+C) by restoring stdin and exiting with code 130.
+ *
+ * @returns A {@link PaginationIO} wired to process.stdin and process.stdout.
+ */
+export declare function createDefaultIO(): PaginationIO;

package/lib/utils/pagination/keypress-reader.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/** Exit code for Ctrl+C signal (128 + SIGINT signal number 2). */
+const CTRL_C_EXIT_CODE = 130;
+/**
+ * Create the default terminal I/O implementation for pagination.
+ *
+ * Uses `process.stdin.setRawMode(true)` to read individual keypresses.
+ * Registers a `process.on('exit')` handler to restore stdin state unconditionally.
+ * Handles `\x03` (Ctrl+C) by restoring stdin and exiting with code 130.
+ *
+ * @returns A {@link PaginationIO} wired to process.stdin and process.stdout.
+ */
+export function createDefaultIO() {
+    return {
+        isTTY: Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY),
+        write(text) {
+            process.stdout.write(text);
+        },
+        readKey() {
+            return new Promise((resolve, reject) => {
+                const stdin = process.stdin;
+                const wasRaw = stdin.isRaw;
+                // Guard: setRawMode is only available on TTY streams
+                if (typeof stdin.setRawMode !== 'function') {
+                    reject(new Error('Cannot read keypress: stdin is not a TTY'));
+                    return;
+                }
+                stdin.setRawMode(true);
+                stdin.resume();
+                stdin.setEncoding('utf8');
+                /** Restore stdin to its previous state. */
+                const restore = () => {
+                    stdin.setRawMode(wasRaw ?? false);
+                    stdin.pause();
+                    stdin.removeListener('data', onData);
+                };
+                /** Exit handler to ensure stdin is always restored. */
+                const onExit = () => {
+                    restore();
+                };
+                process.on('exit', onExit);
+                const onData = (data) => {
+                    process.removeListener('exit', onExit);
+                    restore();
+                    // Ctrl+C: restore terminal and exit cleanly
+                    if (data === '\x03') {
+                        process.exit(CTRL_C_EXIT_CODE);
+                        return;
+                    }
+                    resolve(data.length > 0 ? data[0] : 'q');
+                };
+                stdin.once('data', onData);
+            });
+        },
+    };
+}
+//# sourceMappingURL=keypress-reader.js.map

package/lib/utils/pagination/keypress-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keypress-reader.js","sourceRoot":"","sources":["../../../src/utils/pagination/keypress-reader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,kEAAkE;AAClE,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;QAEpE,KAAK,CAAC,IAAY;YAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,OAAO;YACL,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;gBAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;gBAE3B,qDAAqD;gBACrD,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;oBAC3C,MAAM,CAAC,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC,CAAC;oBAC9D,OAAO;gBACT,CAAC;gBAED,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACvB,KAAK,CAAC,MAAM,EAAE,CAAC;gBACf,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBAE1B,2CAA2C;gBAC3C,MAAM,OAAO,GAAG,GAAS,EAAE;oBACzB,KAAK,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;oBAClC,KAAK,CAAC,KAAK,EAAE,CAAC;oBACd,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACvC,CAAC,CAAC;gBAEF,uDAAuD;gBACvD,MAAM,MAAM,GAAG,GAAS,EAAE;oBACxB,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC;gBAEF,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAE3B,MAAM,MAAM,GAAG,CAAC,IAAY,EAAQ,EAAE;oBACpC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;oBACvC,OAAO,EAAE,CAAC;oBAEV,4CAA4C;oBAC5C,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;wBACpB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;wBAC/B,OAAO;oBACT,CAAC;oBAED,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC3C,CAAC,CAAC;gBAEF,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/lib/utils/pagination/paginate-output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Abstraction over terminal I/O for pagination prompts.
+ *
+ * Injected into {@link paginateOutput} to decouple from process.stdin/stdout,
+ * enabling deterministic testing without raw mode manipulation.
+ */
+export type PaginationIO = {
+    /** Whether the I/O streams are connected to an interactive terminal. */
+    isTTY: boolean;
+    /** Write text to the output stream. */
+    write(text: string): void;
+    /** Read a single keypress and return the character. */
+    readKey(): Promise<string>;
+};
+/**
+ * Configuration options for {@link paginateOutput}.
+ */
+export type PaginateOptions = {
+    /** Number of records per page. Defaults to 25. */
+    pageSize?: number;
+    /** Skip interactive prompts — render all records at once. */
+    noPrompt?: boolean;
+    /** Skip pagination when JSON output mode is active. */
+    jsonEnabled?: boolean;
+    /** Injected I/O for testing. Falls back to default terminal IO when omitted. */
+    io?: PaginationIO;
+};
+/**
+ * Result metadata returned after pagination completes.
+ */
+export type PaginateResult = {
+    /** Number of records actually rendered. */
+    displayed: number;
+    /** Total number of pages (may exceed pages displayed if user quit early). */
+    totalPages: number;
+    /** Terminal action: how pagination ended. */
+    action: 'all' | 'paged' | 'quit' | 'no-pagination';
+};
+/**
+ * Paginate a record set with interactive terminal prompts.
+ *
+ * @typeParam T - The record type being paginated.
+ * @param records - Full array of records to paginate.
+ * @param renderPage - Callback invoked for each page (or all records). Receives the slice and its start index.
+ * @param options - Pagination configuration.
+ * @returns Result metadata describing what was displayed and how pagination ended.
+ */
+export declare function paginateOutput<T>(records: T[], renderPage: (items: T[], startIndex: number) => void, options?: PaginateOptions): Promise<PaginateResult>;

package/lib/utils/pagination/paginate-output.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Core pagination utility for CLI output.
+ *
+ * Provides interactive page-by-page rendering for large record sets,
+ * with automatic bypass for non-TTY, JSON mode, and CI environments.
+ * Uses dependency injection via {@link PaginationIO} for testability.
+ *
+ * @module utils/pagination/paginate-output
+ */
+/** Default number of records per page. */
+const DEFAULT_PAGE_SIZE = 25;
+/** Minimum allowed page size to prevent infinite loops. */
+const MIN_PAGE_SIZE = 1;
+/**
+ * Paginate a record set with interactive terminal prompts.
+ *
+ * @typeParam T - The record type being paginated.
+ * @param records - Full array of records to paginate.
+ * @param renderPage - Callback invoked for each page (or all records). Receives the slice and its start index.
+ * @param options - Pagination configuration.
+ * @returns Result metadata describing what was displayed and how pagination ended.
+ */
+export async function paginateOutput(records, renderPage, options) {
+    const pageSize = Math.max(options?.pageSize ?? DEFAULT_PAGE_SIZE, MIN_PAGE_SIZE);
+    const totalPages = records.length === 0 ? 0 : Math.ceil(records.length / pageSize);
+    // Empty records — nothing to do
+    if (records.length === 0) {
+        return { displayed: 0, totalPages: 0, action: 'no-pagination' };
+    }
+    // No pagination needed — fits in a single page
+    if (records.length <= pageSize) {
+        renderPage(records, 0);
+        return { displayed: records.length, totalPages: 1, action: 'no-pagination' };
+    }
+    // Determine if interactive pagination should be used
+    const shouldPaginate = resolveInteractiveMode(options);
+    if (!shouldPaginate) {
+        // Render everything at once
+        renderPage(records, 0);
+        return { displayed: records.length, totalPages, action: 'all' };
+    }
+    // Interactive pagination loop
+    const io = options?.io;
+    if (!io) {
+        // No IO provided and interactive mode resolved — fallback to render all.
+        // In production, createDefaultIO() from keypress-reader.ts should be passed.
+        renderPage(records, 0);
+        return { displayed: records.length, totalPages, action: 'all' };
+    }
+    // Render first page, then enter prompt loop
+    const firstPageSlice = records.slice(0, pageSize);
+    renderPage(firstPageSlice, 0);
+    return promptLoop(records, renderPage, io, pageSize, totalPages, firstPageSlice.length);
+}
+/**
+ * Interactive prompt loop that handles page-by-page navigation.
+ *
+ * Separated from the main function to satisfy the no-await-in-loop lint rule
+ * while maintaining clear sequential pagination semantics.
+ */
+async function promptLoop(records, renderPage, io, pageSize, totalPages, initialDisplayed) {
+    let currentPage = 1;
+    let displayed = initialDisplayed;
+    // Read first key
+    io.write(`Page ${currentPage} of ${totalPages} — (N)ext, (A)ll, (Q)uit`);
+    let key = await io.readKey();
+    /* eslint-disable no-await-in-loop -- Interactive pagination requires sequential keypress reads between page renders */
+    while (currentPage < totalPages) {
+        const normalizedKey = key.toLowerCase();
+        if (normalizedKey === 'q') {
+            return { displayed, totalPages, action: 'quit' };
+        }
+        if (normalizedKey === 'a') {
+            // Render all remaining records at once
+            const remaining = records.slice(currentPage * pageSize);
+            renderPage(remaining, currentPage * pageSize);
+            return { displayed: records.length, totalPages, action: 'all' };
+        }
+        if (normalizedKey === 'n') {
+            const start = currentPage * pageSize;
+            const end = Math.min(start + pageSize, records.length);
+            const pageSlice = records.slice(start, end);
+            renderPage(pageSlice, start);
+            displayed += pageSlice.length;
+            currentPage++;
+            // If we've reached the last page, exit cleanly
+            if (currentPage >= totalPages) {
+                return { displayed, totalPages, action: 'paged' };
+            }
+        }
+        // Prompt for next action
+        io.write(`Page ${currentPage} of ${totalPages} — (N)ext, (A)ll, (Q)uit`);
+        key = await io.readKey();
+    }
+    /* eslint-enable no-await-in-loop */
+    return { displayed, totalPages, action: 'paged' };
+}
+/**
+ * Determine whether interactive pagination should be used.
+ *
+ * Returns false (skip pagination) when any of these conditions hold:
+ * - `noPrompt` option is true
+ * - `jsonEnabled` option is true
+ * - Explicit IO is provided and `io.isTTY` is false
+ * - No explicit IO and `CI` environment variable is set to 'true'
+ * - No explicit IO and `TERM` environment variable is 'dumb'
+ *
+ * When an explicit `io` is provided, `io.isTTY` is the sole gate — env vars do not apply.
+ * This isolates tests that inject MockPaginationIO from the CI environment.
+ * When no `io` is provided, env vars are checked as a fallback terminal detection mechanism.
+ */
+function resolveInteractiveMode(options) {
+    if (options?.noPrompt === true)
+        return false;
+    if (options?.jsonEnabled === true)
+        return false;
+    // When explicit IO is provided, defer entirely to io.isTTY.
+    // Callers that inject IO are responsible for setting isTTY correctly (e.g. createDefaultIO()).
+    if (options?.io !== undefined) {
+        return options.io.isTTY;
+    }
+    // No explicit IO — check environment variables for CI/dumb terminal
+    if (process.env.CI === 'true')
+        return false;
+    if (process.env.TERM === 'dumb')
+        return false;
+    return true;
+}
+//# sourceMappingURL=paginate-output.js.map

package/lib/utils/pagination/paginate-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate-output.js","sourceRoot":"","sources":["../../../src/utils/pagination/paginate-output.ts"],"names":[],"mappings":"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"}

package/messages/compatibility.check.md

@@ -0,0 +1,71 @@
+# summary
+
+Verify the Cuneiform For Salesforce app version required by this CLI build, and (optionally) the version installed in a target org.
+
+# description
+
+Reports the Cuneiform For Salesforce managed-package version this CLI release was tested against. Without `--target-org`, the command is a local-only readout — no Salesforce API calls, no authentication required.
+
+When `--target-org` is supplied, the command queries the org for the installed Cuneiform For Salesforce package via the Tooling API and reports one of five states:
+
+- `installed-match` — installed version satisfies the requirement (exit 0)
+- `installed-newer` — installed version is newer than required (exit 0, advisory)
+- `installed-version-unknown` — Cuneiform is detected via namespace but the version is not exposed (typical for source-pushed scratch orgs — CLI-1569). Compatibility cannot be verified, but the package is present (exit 0, advisory)
+- `installed-older` — installed version is older than required (exit 1)
+- `not-installed` — Cuneiform For Salesforce is not installed in this org (exit 1)
+
+Use this command to:
+
+- Confirm a scratch org or sandbox is ready for CLI operations after a fresh package install
+- Diagnose CLI errors that look like data-shape mismatches but are version-compatibility issues
+- Pin CLI/app version pairs in CI before running profiling jobs
+
+# examples
+
+- Print the required app version (no auth, no API calls):
+
+  <%= config.bin %> <%= command.id %>
+
+- Verify the installed version in a target org:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Machine-readable output for CI:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+# flags.target-org.summary
+
+Target org username or alias. When supplied, the command queries the org's installed Cuneiform For Salesforce version and reports compatibility.
+
+# flags.api-version.summary
+
+API version to use when querying the target org. Defaults to the org's maximum supported version.
+
+# state.installed-match
+
+✓ Installed version matches the required version. Compatible.
+
+# state.installed-newer
+
+✓ Installed version is newer than required. Likely compatible — newer org-side features may not be exposed by this CLI build.
+
+# state.installed-version-unknown
+
+⚠ Cuneiform For Salesforce is present in this org (detected via namespace) but the package version is not exposed by the standard API. This is typical for source-pushed scratch orgs. Compatibility cannot be verified against the requirement — proceed at your own risk.
+
+# state.installed-older
+
+✗ Installed version is older than required. CLI commands that depend on newer app features will fail. Upgrade Cuneiform For Salesforce in this org to at least the required version.
+
+# state.not-installed
+
+✗ Cuneiform For Salesforce is not installed in this org. Install the managed package before running CLI commands.
+
+# errors.manifestInvalid
+
+This CLI build's `package.json` is missing the `cuneiform.requiredAppVersion` field. This is a build-time configuration error — please file an issue on the salesforce-cli repository.
+
+# errors.orgQueryFailed
+
+Failed to query the installed package version from the target org: %s

package/messages/cuneiform.access.md

@@ -0,0 +1,138 @@
+# error.profilingAccessDenied
+
+Cuneiform is installed, but you don't have profiling access.
+
+You're missing one or more required permission sets.
+
+Next steps:
+
+1. Run the diagnostic to see exactly what's missing:
+   sf cuneiform user details --target-org <your-org>
+
+2. Preview what the auto-configure would change:
+   sf cuneiform user details --target-org <your-org> --configure --dry-run
+
+3. Apply the changes automatically:
+   sf cuneiform user details --target-org <your-org> --configure
+
+If you don't have permission to self-configure, ask your Salesforce administrator to assign the required Cuneiform permission sets.
+
+# error.globalProfilingNotEnabled
+
+Cuneiform is installed, but Global Profiling is not enabled.
+
+API-Only Profiling must be enabled in the Configuration Profile before you can use the CLI.
+
+Next steps:
+
+1. Run the diagnostic to see your current readiness:
+   sf cuneiform user details --target-org <your-org>
+
+2. Preview what the auto-configure would change:
+   sf cuneiform user details --target-org <your-org> --configure --dry-run
+
+3. Apply the changes automatically:
+   sf cuneiform user details --target-org <your-org> --configure
+
+If you don't have permission to self-configure, ask your Salesforce administrator to enable API-Only Profiling in the Cuneiform Configuration Profile.
+
+# error.cuneiformNotInstalled
+
+Cuneiform for Salesforce is not installed in this org.
+
+The Cuneiform for Salesforce CLI is available exclusively to PeerNova customers with an active license. The managed package must be installed and activated before you can use the CLI.
+
+Next steps:
+
+1. If you are a PeerNova customer, contact your Salesforce administrator to install the package.
+
+2. If you need to obtain a license, request one at:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/4196499551
+
+3. To get Cuneiform for Salesforce:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/2624356353
+
+4. Once installed, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+For help: sfsupport@peernova.com
+
+# error.selfRegistrationNotEnabled
+
+Cuneiform is installed and API-Only Profiling is enabled, but CLI self-provisioning is not available.
+
+Your administrator has not enabled CLI self-provisioning for API-based profiling. This setting ensures your admin controls which users can configure their own API profiling access — you're one admin action away from full access.
+
+Next steps:
+
+1. Run the diagnostic to see your full readiness status:
+   sf cuneiform user details --target-org <your-org>
+
+2. Ask your Salesforce administrator to enable "Enable API Profiling Self-Registration"
+   in the Cuneiform Configuration Profile (Custom Metadata).
+
+3. Alternatively, your admin can assign the API-Based Profiling permission set to you
+   directly, bypassing self-provisioning.
+
+# error.featureNotEnabled
+
+API-Based Profiling is not enabled for this organization.
+
+The Cuneiform for Salesforce CLI is available exclusively to PeerNova customers with an active license. This feature must be enabled by PeerNova before you can use the CLI.
+
+Next steps:
+
+1. If you are a PeerNova customer, contact your PeerNova account team to enable
+   API-Based Profiling for your organization.
+
+2. If you need to obtain a license, request one at:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/4196499551
+
+3. To get Cuneiform for Salesforce:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/2624356353
+
+4. Once enabled, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+For help: sfsupport@peernova.com
+
+# error.environmentConfigureBlocked
+
+Configuration is not allowed in production environments.
+
+The configure and autoconfigure commands are restricted to non-production orgs to protect your production data. This org has been identified as a Production org.
+
+Next steps:
+
+1. Run the diagnostic to confirm your org type:
+   sf cuneiform user details --target-org <your-org>
+
+2. Use a sandbox, scratch org, or developer org to test configuration:
+   sf cuneiform user details --target-org <sandbox-org> --configure
+
+3. If you believe this org was misidentified, contact your Salesforce administrator to verify the org type.
+
+# error.connectionFailed
+
+Could not verify your Cuneiform access. The connection to your org failed before the access check could run.
+
+Detail: %s
+
+Next steps:
+
+1. Verify your org is authenticated:
+   sf org list --all
+
+2. Re-authenticate if needed:
+   sf org login web --alias <your-org>
+
+3. Once connected, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+If the problem persists, check your network connection and ensure the Salesforce instance is reachable.
+
+# error.accessCheckFailed
+
+Could not verify your Cuneiform access.
+
+%s