agentknock secret upload

agentknock secret upload NAME reads local secret data and sends a proposal to your paired phone. A successful command means the phone has saved the proposal for review. The proposed change takes effect only after you approve it in the app; the CLI doesn’t wait for that decision.

The command requires a completed pairing and at least one source of secret data. Uploading leaves the source files, environment variables, and keys unchanged.

Upload environment variables

To create a secret named github from GH_TOKEN in the current environment:

agentknock secret upload github --from-env GH_TOKEN

You can combine these sources:

Option	Behavior
--from-env NAME	Reads an exported variable from the CLI’s process environment and stores it under the same name. An unset variable is an error.
--from-file NAME=PATH	Stores the complete file contents as NAME, including leading whitespace and trailing newlines.
--from-prompt NAME	Reads a value from the controlling terminal without displaying it and stores it as NAME. Press Enter to finish.
--from-env-file PATH	Parses the given dotenv file and adds its names and values to the secret.

Repeat any source option to read more values. Each variable name can appear only once across all sources, including within a dotenv file. Duplicates are errors even when the values match; option order doesn’t choose a winning value.

Environment variable names must start with an ASCII letter or underscore and contain only ASCII letters, digits, and underscores. Values may be empty, but cannot contain null bytes. All input must be valid UTF-8.

Agentknock reads and validates all input before sending the proposal. An unreadable source, invalid value, or failed prompt stops the upload. The resulting environment secret must contain at least one variable; an empty dotenv file alone is insufficient.

Standard input and prompts

Use --from-file NAME=- to read one value from standard input, or --from-env-file - to parse standard input as dotenv data. Both read until end of input. At most one source can read standard input in a single upload.

Hidden prompts use the controlling terminal, so they can accompany a source that reads standard input. They require an interactive terminal; use file or environment sources when running unattended.

Dotenv files

--from-env-file PATH reads the specified file; it doesn’t search for .env or execute a shell script. Repeating the option combines files subject to the duplicate-name rule above.

The parser accepts NAME=value assignments, optional export prefixes, blank lines, and # comments. Quotes are removed from values. Single quotes preserve literal text; double quotes allow variable expansion and escapes such as \n for a newline. Quoted values can span multiple lines.

Use ${NAME} for variable expansion. Without braces, an underscore ends the variable name: $API_TOKEN expands API and appends the literal text _TOKEN. Use ${API_TOKEN} to expand the full name.

Expansion looks first in the CLI’s process environment, then at earlier assignments in the same file. An undefined reference expands to an empty string. Separate files don’t share their earlier assignments, and parsing a file doesn’t change the process environment.

Use single quotes around a dotenv value containing literal dollar signs, or --from-file NAME=PATH to preserve a file’s contents without dotenv parsing.

Upload an SSH key

--from-ssh-key PATH reads an OpenSSH private-key file. It cannot be combined with environment-variable sources. Use --from-ssh-key - to read the key from standard input.

For a passphrase-protected key:

agentknock secret upload git-signing --from-ssh-key ~/.ssh/id_ed25519 --passphrase-prompt

Choose one passphrase source for an encrypted key:

Option	Behavior
--passphrase-prompt	Reads the passphrase from a hidden prompt on the controlling terminal.
--passphrase-env NAME	Reads the passphrase from the named process environment variable, allowing noninteractive use. The variable must be set and contain valid UTF-8.

Both options require --from-ssh-key and cannot be combined. For an unencrypted key, omit them; supplying a passphrase option is an error. An encrypted key without a passphrase option also fails instead of prompting automatically. An incorrect passphrase stops the upload.

Agentknock decrypts the key locally and uploads it without its original passphrase protection. It never sends the passphrase. The upload uses end-to-end encryption, and the phone stores accepted secrets encrypted.

The source must use OpenSSH private-key format. To convert a legacy PEM key, run ssh-keygen -p -f PATH before uploading. That separate conversion command rewrites the key file.

Create, update, or replace

NAME is the proposed name for a new secret or the exact name of an existing one. It cannot be empty or contain a comma. Quote names containing spaces.

Mode	Effect when you approve the proposal
Create (default)	Creates a new secret. You can change its proposed name when accepting it on the phone.
--update	Updates an existing secret. Supplied environment variables are added or changed; variables you omit are retained.
--replace	Replaces an existing secret’s contents. Environment variables you omit are removed.

For example, if deployment already contains TOKEN and ACCOUNT_ID, uploading only TOKEN with --update keeps ACCOUNT_ID. The same upload with --replace removes ACCOUNT_ID when accepted. An empty value sets a variable to an empty string; it doesn’t remove that variable.

Update and replace require the exact name of an existing secret and cannot rename it. The CLI sends that name to the phone without first looking up the secret. You cannot combine --update and --replace.

Every SSH upload includes a private key, so both update and replace propose replacing the existing key. For both secret types, the modes also determine what happens to an omitted description.

Description

--description TEXT supplies the proposed description. In update mode, omit it to keep the existing description or use --description "" to remove it. In create and replace modes, omitting the option produces a secret without a description.

The CLI requires secret data even when changing only a description: provide at least one environment variable or an SSH private key. Use the phone’s secret editor for a description-only change without resupplying secret data.

Completion and review

While waiting for receipt, the CLI reports progress and elapsed time to standard error every 30 seconds. On success, it writes a delivery confirmation and a reminder to review the proposal to standard output. There is no JSON output mode for uploads.

The phone can reject a proposal before saving it for review. In that case, the CLI exits unsuccessfully and reports the phone’s rejection message. A later approval or rejection in the app doesn’t change the completed command’s result.

If the request fails or you interrupt it while waiting for receipt, check the phone before retrying: the proposal may already have arrived. Once the CLI has verified that the phone saved the proposal, an interruption or connection failure during the final confirmation still leaves the command successful.

On the phone, open Secrets and select the incoming upload to review and approve it. For an update or replacement, the existing secret remains unchanged until approval.