Arc CLI

Arc CLI's Connect commands record literal Arc Item markers in Git and upload file/line locations to Arc. It uses Python 3.11 or later and Click, with plain terminal prompts. The standalone package is MIT licensed; Arc's application/backend licence is unchanged.

python -m pip install --upgrade archelps
arc connect init

Setup and generated CI use the latest published package without a version constraint. --upgrade also updates an existing installation.

The executable is arc. Connect groups the existing Git workflow under arc connect init, arc connect scan and arc connect upload; arc logout clears the saved sign-in. Setup handles browser sign-in. There is no separate login command or general API command group.

Run setup in an interactive terminal inside a GitHub.com or GitLab.com repository. Self-hosted GitLab is not currently supported. Sign in through Cognito in the browser, then return to the terminal. Choose one Organization and one or more Programs by name or number; confirm each Program's repository-specific marker label immediately after selection. Existing registered labels are frozen and reused. Confirm the repository/default branch, then choose GitHub Actions, GitLab CI or other CI independently of the repository host. Declining repository confirmation cancels setup; rerun with --repository-url and --default-branch to correct it.

Setup writes secrets-free .arc/config.json with schema_version, api_url, organization_id, git, ci, programs and marker_instructions. git contains provider, canonical repository URL and default branch. Each Program entry contains program_id, frozen label, source_id and token_env (ARC_TOKEN_<LABEL>). Custom setup configuration paths must stay inside the repository for CI. Commit the configuration and generated CI file, including the config if Git ignore rules exclude it. Setup creates no hooks, tracked mapping/data file or customer README.

Credentials and recovery

Setup automatically creates one personal write token per Program/source through the OAuth-only POST /programs/{program_id}/code-links/sources/{source_id}/token route. Source setup requires program.manage; token issuance also requires program.edit and the normal personal-token membership/MFA rules. Write mode does not grant Program permissions. Uploads recheck current authority.

Returned secrets are saved outside the repository in a private ~/.arc-connect/ci-<hash>.json, partitioned by checkout, API target and signed-in account. The CLI prints only that path and CI secret names. Read the private file and paste each value into its named CI secret or masked/protected variable, such as ARC_TOKEN_BRAKES. Upload reads these environment variables; it does not read the private handoff file.

Repeated init reuses saved settings and local credentials. A secrets-free draft under Git's private metadata preserves selected Programs/labels during interrupted registration. Configuration is saved before token issuance/CI generation. If an existing server token has no local copy, setup requires an explicit replacement choice; declining preserves it. arc connect init --replace-tokens deliberately revokes and replaces only the current user's configured source tokens. Update CI secrets afterward. No setup mutation is automatically retried after an uncertain response.

Use arc connect init --reconfigure to choose Organization, Programs, repository or CI again. An explicit API target conflicting with saved setup fails before authentication unless reconfiguration is requested. Repeating init reconnects a removed source through the existing source service. Superseded hooks/root files have no compatibility path and are not deleted automatically.

Cognito credentials are cached separately at ~/.arc-connect/tokens.json, with private permissions, PKCE S256, state validation and domain/client/resource/scope binding. Redirects do not receive bearer credentials. An expired refresh credential reopens sign-in. arc logout clears a corrupt cache or revokes the cached refresh token and removes the cache; it warns when revocation cannot be confirmed. Issued access tokens can remain valid for up to 15 minutes. Personal CI tokens remain separately managed.

HTTPS uses Python's default trusted certificates plus certifi's bundled roots. An explicit SSL_CERT_FILE or SSL_CERT_DIR selects only that configured trust store. Certificate errors retain saved credentials and stop with a clear error; they do not reopen sign-in or retry uploads. Certificate and hostname checks stay enabled.

Production defaults are API transport https://api.archelps.com/api/v1/public, Cognito domain https://arc5-production.auth.eu-west-2.amazoncognito.com, public API client 3foiu1p2hb5nm09dc95g5c4m0j, and audience/scope resource https://arc5-api.onrender.com/api/v1/public. Transport and audience are distinct. Use --api-url, --cognito-domain, --client-id, --resource and --cache for another environment. ARC_API_URL, ARC_COGNITO_DOMAIN, COGNITO_API_CLIENT_IDS and ARC_API_RESOURCE are also supported. Custom OAuth cache paths must remain outside Git; the CI handoff is saved beside that cache.

Literal markers and scanning

Copy the real marker from an Arc Item and place it near associated code or tests:

# ARC-BRAKES-REQ-001
def stop():
    ...

The syntax is ARC-<PROGRAM_LABEL>-<ITEM_IDENTIFIER>. Labels use uppercase ASCII letters, digits and underscores, start with a letter and have at most 32 characters. Canonical Item prefixes are SYS, REQ, PROP, TST, TPL and RSK, followed by at least three digits. Leading zeros and the literal marker are preserved; several markers can share a line. Unicode word characters and hyphens prevent matches embedded in longer identifiers. Never invent identifiers or substitute import identifiers. Coding agents can read .arc/config.json for configured labels and marker guidance. A code link is not proof that an Item's obligation is met.

arc connect scan prints deterministic schema 1.0.0 JSON from one exact HEAD commit without writing files or changing the index. Sequential Git search scans tracked regular text; binary/LFS/submodule/symlink payloads, .arc/ and a custom config path are excluded. There is no AI, language parser, concurrency or incremental cache. Git failures never produce successful empty reports. --repo selects a checkout and --config a secrets-free configuration path relative to its Git root; Connect's common options are accepted before or after its init, scan or upload subcommand.

CI reports

GitHub Actions generates .github/workflows/arc.yml: a separate default-branch push workflow that checks out the exact event SHA, installs the latest published package and runs arc connect upload with continue-on-error: true.

GitHub, GitLab and other-CI instructions all install with python -m pip install --upgrade archelps, without a version constraint.

GitLab CI generates .arc/gitlab-ci.yml; append the printed include to your existing .gitlab-ci.yml, merging with existing includes:

include:
  - local: '/.arc/gitlab-ci.yml'

Select GitLab CI during setup, or run arc connect init --ci gitlab. In the GitLab project, open Settings → CI/CD → Variables and add each named ARC_TOKEN_<LABEL> from the private handoff file as a masked variable. Use protected variables only when the configured default branch is protected. Commit .arc/config.json, .arc/gitlab-ci.yml, the include and your Item markers, then push to that branch. A runner must be available. Check the arc job's upload output, then Arc's Last sync and the Item's Code links; the job allows failure, so a successful overall pipeline does not prove the upload succeeded.

Its job uses default-branch push rules with when: always, stage .post and allow_failure: true, so earlier job failures do not skip it. Global workflow rules must still allow that pipeline to be created. Existing customer files and symlinks are preserved; setup prints generated content for manual insertion when needed and never rewrites the customer's GitLab pipeline. Changing CI removes only Arc-generated files for the other CI choice and prints a reminder to remove an obsolete GitLab include.

Other CI receives exact-checkout, secret and nonblocking-step instructions. After checking out the exact event commit, pass the commit and branch together for a detached checkout, using your CI's actual event variables:

arc connect upload --commit-sha "$YOUR_CI_COMMIT_SHA" --branch "$YOUR_CI_BRANCH"

Configure the step to allow failure. GitHub/GitLab events are checked automatically; a mismatched checkout fails before sending and other branches skip. Keep CI token names from .arc/config.json and do not expose tokens to pull-request pipelines.

Upload scans one pinned commit and generates JSON in memory. One complete data format, schema_version: "1.0.0", contains the full commit_sha, scanner_version and git repository identity with Program UUID/label marker locations. Each Program is sent separately through its own token to POST /api/v1/public/programs/{program_id}/code-links/sources/{source_id}/reports. Reports are bounded to 32 MiB and 500,000 locations. Network, 429 and 5xx failures use at most three total attempts with identical bodies; other API failures do not retry. Missing/failed tokens do not prevent remaining Program uploads; the direct command returns nonzero if any fail while generated CI remains nonblocking.

data.schema.json describes both scan output and uploads; there is no nested report wrapper. Scan output can contain all configured Programs; each upload contains exactly one Program matching its token and route. Config's independent schema_version remains integer 1, and the CLI package version is 0.1.1. Future data-schema releases must deploy server acceptance before publishing a CLI that sends the new format. The current data schema remains 1.0.0; no compatibility implementation is added by this release policy. No source text or secrets are uploaded. Arc retains five report bodies and resolved projections, with older deduplication receipts. Invalid/failed reports preserve current links; complete empty reports clear them. Duplicate retries never promote old reports. Removal hides links and disables uploads; identical source reconnection restores the retained current report. These links do not create Item revisions or appear in historic model views.

Development

python -m pip install '.[test]'
# Run only tests created or edited for the current change; for example:
python -m pytest --confcutdir=. tests/test_setup.py::test_noninteractive_init_does_not_open_browser
python -m build

The standalone archelps package root maps the existing arc_connect Python module to this directory and does not package the Arc backend or its dependencies. Click and certifi are the runtime dependencies. The internal module name and private ~/.arc-connect credential location are unchanged.